ap-chain

README

🤖 AP Chain

🌟 概要

AP Chain は、大量のウェブページから情報を並列に取得し、GeminiのMapReduce処理(セグメントごとのクリーンアップ → 統合・構造化)によって、重複を排除した構造化文書を生成するGo製CLIツールです。

AIの出力はResponseSchemaでJSON構造化して安定させ、そのJSONから決定的にMarkdownを組み立てて公開します。各セクションには、根拠となった出典URLが自動的に付与されます。

---

🛠️ 主要な機能と設計の特長

LLMマルチステップ処理（MapReduce型）

巨大な情報を「分割・要約・統合」のステップで処理し、コンテキストウィンドウの制限を克服します。

• Mapフェーズ: セグメント化された各テキストから中間要約を並列生成。
• Reduceフェーズ: 中間情報を統合し、重複を排除。論理的なセクション（##）へと再構成します。
• トレーサビリティ: 各セクションの直後に、情報源となった参照元URLリストを自動付与します。

🔔 通知とセキュアな共有

• Slack連携: 処理の完了（成功・失敗）を即座にSlackへ通知します。
• 署名付きURL (Signed URL): 生成されたMarkdownに対して、一時的な閲覧権限を持つ署名付きURLを発行。非公開のGCSバケットでも安全に結果を共有可能です。

---

✨ 技術スタック

要素	技術 / ライブラリ	役割
言語	Go (Golang)	ツールの開発言語。並列処理と堅牢な実行環境を提供します。
CLI	Cobra	コマンドライン引数とオプションの解析に使用します。

🧱 基盤ライブラリ (Core Components)

AP Chain は以下の自作ライブラリ群を統合して構築されています：

• Go Web Reader: マルチプロトコル I/O と本文抽出。
• Go Remote IO: GCS/ローカルストレージの抽象化。
• Go Web Exact: 高精度なメインコンテンツ抽出。
• Go Notify: Webhookを利用したSlack通知。

---

🛠️ 事前準備と設定

Gemini API を利用するために、APIキーが必要です。設定は以下のどちらかの方法で行います。

# GCP プロジェクトID
export GCP_PROJECT_ID="YOUR_GCP_PROJECT_ID"
# Gemini API キー
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
# Slack Webhook URL (任意: 指定すると通知が有効になります)
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

---

🚀 使い方 (Usage)

本ツールは、処理対象のURLを記載したファイルを読み込む形式のみをサポートします。

実行コマンド形式とオプション

オプション	フラグ	説明	デフォルト値
--input	-i	処理対象のURLリストを記載したファイルパスを指定します。ローカルパスまたはGCS URI (gs://...) を指定できます。 (必須)	なし
--output	-o	最終的な構造化結果の出力先パスを指定します。ローカルパスまたはGCS URI (gs://...) を指定できます。GCS URIを指定した場合、ローカルへの出力はスキップされます。	./output/output.md

---

🔄 シーケンスフロー (Sequence Flow)

sequenceDiagram
    autonumber
    actor User as User
    participant CLI as Cobra CLI
    participant AppBuilder as builder.BuildContainer
    participant Pipeline as pipeline.Pipeline
    participant Collector as runner.CollectRunner
    participant Source as Input File / GCS
    participant Scraper as go-web-exact ScrapeRunner
    participant Composer as runner.ComposeRunner
    participant LLM as adapters.ComposerAdapter
    participant Publisher as runner.PublishRunner
    participant Storage as go-remote-io Writer/Signer
    participant Slack as adapters.SlackAdapter

    User->>CLI: ap-chain generate -i urls.txt -o output.md
    CLI->>AppBuilder: BuildContainer(ctx, config)
    AppBuilder-->>CLI: app.Container
    CLI->>Pipeline: Execute(ctx, req)

    Pipeline->>Collector: Run(ctx, inputURI)
    Collector->>Source: Open(inputURI)
    Source-->>Collector: URL list content
    Collector->>Collector: Parse and validate URLs
    Collector->>Scraper: Run(ctx, urls)
    Scraper-->>Collector: scraped contents
    Collector-->>Pipeline: []URLResult

    Pipeline->>Composer: Run(ctx, urlResults)
    Composer->>Composer: Segment content per URL
    Composer->>LLM: RunMap(model, segments) [ResponseSchema: cleaned_text]
    LLM-->>Composer: cleaned segments (text + original URL)
    Composer->>LLM: RunReduce(model, cleaned segments) [ResponseSchema: title/sections]
    LLM-->>Composer: structured report JSON
    Composer-->>Pipeline: structured report JSON

    Pipeline->>Publisher: Run(ctx, outputURI, reportJSON)
    Publisher->>Publisher: Convert JSON to Markdown (deterministic)
    Publisher->>Storage: Write markdown
    Publisher->>Storage: GenerateSignedURL(markdown)
    Storage-->>Publisher: markdown URL
    Publisher-->>Pipeline: PublishResult

    Pipeline->>Slack: NotifySuccess(outputURI, publicURL, sourceCount)
    Slack-->>Pipeline: notification result

    alt any step fails
        Pipeline->>Slack: NotifyFailure(error)
        Slack-->>Pipeline: notification result
    end

---

📜 ライセンス (License)

このプロジェクトは MIT License の下で公開されています。

Documentation

Overview

Command ap-chain は、URL一覧を収集し Gemini の MapReduce で構造化文書へまとめる CLI です。