guinness-ai-v2 ディレクトリアーキテクチャ

V2 AI ワーカーは guinness-ai-v2 モノレポに配置されており、共有パッケージと 3 つの Lambda ベースのアプリ（design-import、code-import、des2code）を含みます。インフラストラクチャの概要（システムアーキテクチャ、データフロー、Webhook 契約）については AI インフラストラクチャを参照してください。

リポジトリ構成

guinness-ai-v2/
  packages/
    agentic/
      __init__.py             # 再エクスポート: build_manager_agent, build_tool_agent 等
      types.py                # AgentDefinition, SkillDefinition（共有モデル）
      orchestrator.py         # build_manager_agent(), build_tool_agent() — PydanticAI
      loader.py               # load_agent_markdown(), discover_skills_for_app()
      registry.py             # スキル ID → ランタイムビルダーのマッピング
      runtime.py              # 共有スキルランタイムビルダー
      agents/
        __init__.py
        vision.py             # Vision エージェントビルダー + DesignDescription 出力モデル
        code_gen.py           # コード生成エージェントビルダー（des2code 用）
    models/
      documentdb/
        __init__.py           # initialize_collections()
        design.py             # DesignCollection、ベクトルインデックス作成
        code.py               # CodeCollection、ベクトルインデックス作成
    helpers/
      __init__.py
      s3.py                   # parse_s3_url()、download_image_from_s3()、download_json_from_s3()
      embedding.py            # generate_embeddings() — 共有 openai SDK 埋め込みユーティリティ
      webhook.py              # send_webhook() — 共有 WEBHOOK_BASE_URL への HTTP POST
    utils/
      __init__.py
      settings.py             # 共有 Pydantic Settings 基底クラス
      documentdb.py           # 共有 DocumentDB 接続シングルトン
  apps/
    design_import/
      src/
        main.py               # Lambda ハンドラー
        config/
          env.py              # Pydantic Settings
          database.py         # DocumentDB 接続
        schemas.py            # Pydantic モデル
        db.py                 # DocumentDB アップサート
    code_import/
      src/
        main.py               # Lambda ハンドラー
        config/
          env.py
          database.py
        schemas.py
        db.py
    des2code/
      src/
        main.py               # Lambda ハンドラー
        config/
          env.py
          database.py
        schemas.py
        db.py
        prompt.py             # マルチモーダルプロンプトビルダー

計画中の機能も同じ app 構成と命名規則に従います。apps/page-import/src/page_import は 1 ページのキャプチャを検証し、apps/code2wf/src/code2wf は完了済み Page Import を既存WF2Des DesignSpecModel に変換し、apps/page-import-cli/src/page_import_cli は信頼されたローカル/CI 環境でキャプチャを実行します。apps/page-import-cli は、既存の apps/* 規約に従い、ルートの uv workspace member に明示的に追加する必要があります。

共有パッケージ責務

ファイル	責務
`packages/agentic/orchestrator.py`	`build_manager_agent()`, `build_tool_agent()` — 共有 PydanticAI ビルダー
`packages/agentic/agents/vision.py`	Vision エージェントビルダー + `DesignDescription` 出力モデル
`packages/agentic/agents/code_gen.py`	コード生成エージェントビルダー（des2code 用）
`packages/helpers/embedding.py`	`generate_embeddings()` — 共有 `openai` SDK 埋め込みユーティリティ
`packages/helpers/webhook.py`	`send_webhook()` — 共有 WEBHOOK_BASE_URL への HTTP POST
`packages/helpers/s3.py`	`parse_s3_url()`, `download_image_from_s3()`, `download_json_from_s3()`
`packages/models/documentdb/design.py`	`DesignCollection`, ベクトルインデックス作成
`packages/models/documentdb/code.py`	`CodeCollection`, ベクトルインデックス作成
`packages/utils/settings.py`	共有 Pydantic Settings 基底クラス
`packages/utils/documentdb.py`	共有 DocumentDB 接続シングルトン

共有依存パッケージ

パッケージ	用途
`openai`	OpenAI API クライアント（直 SDK で埋め込み、PydanticAI `openai:` プロバイダーでチャット）
`pydantic-ai`	PydanticAI — エージェントオーケストレーション、ストリーミング、プロバイダー非依存
`pydantic`	データモデル、構造化出力
`pydantic-settings`	環境変数設定
`pymongo`	DocumentDB（MongoDB）ドライバー
`boto3`	AWS SDK（S3 ダウンロード）
`loguru`	構造化ログ
`httpx`	HTTP クライアント（Webhook POST）

環境変数

変数	ワーカー	説明	例
`OPENAI_API_KEY`	design-import, code-import	OpenAI API キー	`sk-...`
`DOCUMENTDB_CONNECTION_STRING`	全ワーカー	DocumentDB 接続文字列	`mongodb://...`
`DOCUMENTDB_NAME`	全ワーカー	DocumentDB データベース名	`guinness_ai`
`WEBHOOK_BASE_URL`	全ワーカー	バックエンド Webhook URL（プライベート VPC）	`https://api.internal/v1/webhooks/ai-status`
`WEBHOOK_API_KEY`	全ワーカー	backend webhook へ `X-API-Key` として送る shared service key	`...`
`DESC_MODEL`	design-import, code-import	Vision + キーワード抽出モデル（プロバイダー前置詞付き）	`openai:gpt-5.4-nano`
`EMBEDDING_MODEL`	design-import, code-import	埋め込みモデル	`text-embedding-3-large`
`EMBEDDING_DIMENSIONS`	design-import, code-import	DocumentDB metadata と vector index に使う embedding dimension	`512`
`DESIGN_TABLE_NAME`	design-import, des2code	DocumentDB デザインコレクション	`design`
`CODE_TABLE_NAME`	code-import, des2code	DocumentDB コードコレクション	`code`
`RESULT_BUCKET`	des2code	timestamp 付き result artifact 用 S3 bucket	`dev-guinness-backend`
`DES2CODE_RESULT_TTL_DAYS`	des2code	artifact retention metadata / lifecycle expectation	`30`
`VISUAL_SIMILARITY_WEIGHT`	des2code	デュアル検索の Visual 類似度重み	`0.0`
`SEMANTIC_SIMILARITY_WEIGHT`	des2code	デュアル検索の Semantic 類似度重み	`1.0`
`S3_BUCKET_NAME`	page-import（計画中）	Page Import の source/normalized artifact を保存する S3 bucket	`dev-guinness-backend`
`RESULT_BUCKET`	code2wf（計画中）	Code2WF result artifact 用 S3 bucket	`dev-guinness-backend`

計画中の Page Import と Code2WF worker は S3 artifact を使用し、DocumentDB には接続しません。Playwright は repository-side Page Import CLI だけで使用し、Lambda runtime には含めません。