guinness-ai-v2 Directory Architecture

The V2 AI workers live in the guinness-ai-v2 monorepo, containing shared packages and three Lambda-based apps (design-import, code-import, des2code). For the infrastructure overview (system architecture, data flow, webhook contract), see AI Infrastructure.

Repository Structure

guinness-ai-v2/
  packages/
    agentic/
      __init__.py             # Re-exports: build_manager_agent, build_tool_agent, etc.
      types.py                # AgentDefinition, SkillDefinition (shared models)
      orchestrator.py         # build_manager_agent(), build_tool_agent() using PydanticAI
      loader.py               # load_agent_markdown(), discover_skills_for_app()
      registry.py             # Skill ID → runtime builder mapping
      runtime.py              # Shared skill runtime builders
      agents/
        __init__.py
        vision.py             # Vision agent builder + DesignDescription output model
        code_gen.py           # Code generation agent builder (for des2code)
    models/
      documentdb/
        __init__.py           # initialize_collections()
        design.py             # DesignCollection, vector index creation
        code.py               # CodeCollection, vector index creation
    helpers/
      __init__.py
      s3.py                   # parse_s3_url(), download_image_from_s3(), download_json_from_s3()
      embedding.py            # generate_embeddings() — shared openai SDK embedding utility
      webhook.py              # send_webhook() — shared HTTP POST to WEBHOOK_BASE_URL
    utils/
      __init__.py
      settings.py             # Shared Pydantic Settings base class
      documentdb.py           # Shared DocumentDB connection singleton
  apps/
    design_import/
      src/
        main.py               # Lambda handler
        config/
          env.py              # Pydantic Settings
          database.py         # DocumentDB connection
        schemas.py            # Pydantic models
        db.py                 # DocumentDB upsert
    code_import/
      src/
        main.py               # Lambda handler
        config/
          env.py
          database.py
        schemas.py
        db.py
    des2code/
      src/
        main.py               # Lambda handler
        config/
          env.py
          database.py
        schemas.py
        db.py
        prompt.py             # Multi-modal prompt builder

Planned features follow the same app layout and naming convention: apps/page-import/src/page_import validates one captured page, apps/code2wf/src/code2wf converts a completed Page Import into the existing WF2Des DesignSpecModel, and apps/page-import-cli/src/page_import_cli performs trusted local/CI capture. apps/page-import-cli must be added explicitly to the root uv workspace members, following the existing apps/* convention.

Shared Package Responsibilities

File	Responsibility
`packages/agentic/orchestrator.py`	`build_manager_agent()`, `build_tool_agent()` — shared PydanticAI builders
`packages/agentic/agents/vision.py`	Vision agent builder + `DesignDescription` output model
`packages/agentic/agents/code_gen.py`	Code generation agent builder (des2code)
`packages/helpers/embedding.py`	`generate_embeddings()` — shared `openai` SDK embedding utility
`packages/helpers/webhook.py`	`send_webhook()` — shared HTTP POST to WEBHOOK_BASE_URL
`packages/helpers/s3.py`	`parse_s3_url()`, `download_image_from_s3()`, `download_json_from_s3()`
`packages/models/documentdb/design.py`	`DesignCollection`, vector index creation
`packages/models/documentdb/code.py`	`CodeCollection`, vector index creation
`packages/utils/settings.py`	Shared Pydantic Settings base class
`packages/utils/documentdb.py`	Shared DocumentDB connection singleton

Shared Dependencies

Package	Purpose
`openai`	OpenAI API client (embeddings via direct SDK, chat via PydanticAI `openai:` provider)
`pydantic-ai`	PydanticAI — agent orchestration, streaming, provider-agnostic
`pydantic`	Data models, structured output
`pydantic-settings`	Environment variable configuration
`pymongo`	DocumentDB (MongoDB) driver
`boto3`	AWS SDK (S3 downloads)
`loguru`	Structured logging
`httpx`	HTTP client (webhook POST)

Environment Variables

Variable	Workers	Description	Example
`OPENAI_API_KEY`	design-import, code-import	OpenAI API key	`sk-...`
`DOCUMENTDB_CONNECTION_STRING`	all	DocumentDB connection string	`mongodb://...`
`DOCUMENTDB_NAME`	all	DocumentDB database name	`guinness_ai`
`WEBHOOK_BASE_URL`	all	Backend webhook URL (private VPC)	`https://api.internal/v1/webhooks/ai-status`
`WEBHOOK_API_KEY`	all	Shared service key sent as `X-API-Key` to the backend webhook	`...`
`DESC_MODEL`	design-import, code-import	Vision + keyword extraction model (provider-prefixed)	`openai:gpt-5.4-nano`
`EMBEDDING_MODEL`	design-import, code-import	Embedding model	`text-embedding-3-large`
`EMBEDDING_DIMENSIONS`	design-import, code-import	Embedding dimension stored in DocumentDB metadata and used by vector indexes	`512`
`DESIGN_TABLE_NAME`	design-import, des2code	DocumentDB design collection	`design`
`CODE_TABLE_NAME`	code-import, des2code	DocumentDB code collection	`code`
`RESULT_BUCKET`	des2code	S3 bucket for timestamped result artifacts	`dev-guinness-backend`
`DES2CODE_RESULT_TTL_DAYS`	des2code	Artifact retention metadata / lifecycle expectation	`30`
`VISUAL_SIMILARITY_WEIGHT`	des2code	Visual similarity weight for dual search	`0.0`
`SEMANTIC_SIMILARITY_WEIGHT`	des2code	Semantic similarity weight for dual search	`1.0`
`S3_BUCKET_NAME`	page-import (planned)	S3 bucket containing Page Import source and normalized artifacts	`dev-guinness-backend`
`RESULT_BUCKET`	code2wf (planned)	S3 bucket for Code2WF result artifacts	`dev-guinness-backend`

The planned Page Import and Code2WF workers use S3 artifacts and do not connect to DocumentDB. Playwright is limited to the repository-side Page Import CLI and is not included in the Lambda runtime.