guinness-ai-v2 Tech Stack

An overview of the technology stack used across the guinness-ai-v2 monorepo.

Summary

Category	Technology
Language	Python 3.12
Runtime	AWS Lambda
AI framework	PydanticAI
LLM	OpenAI (configured via `provider:model` format)
Embeddings	OpenAI Embeddings API (direct SDK call)
Schema / validation	Pydantic v2
Environment variables	pydantic-settings
Database	Amazon DocumentDB (MongoDB-compatible)
Storage	Amazon S3
Queue	AWS SQS
HTTP client	httpx
AWS SDK	boto3
Logging	loguru
Testing	pytest
Package management	uv workspace

Runtime

Python 3.12 on AWS Lambda

Each worker (design-import, code-import, des2code) runs on Python 3.12 on AWS Lambda. Workers are triggered by SQS and notify the backend via Webhook on completion.

The planned Page Import validator and Code2WF converter follow the same SQS-triggered Lambda pattern. Page capture itself uses Playwright in a trusted local/CI CLI, outside Lambda.

Lambda warm start optimization: DocumentDB clients, S3 clients, and PydanticAI agents are initialized at module level and created only on cold starts.

AI Framework

PydanticAI

Used for agent orchestration. Replaces LangChain / LangGraph from V1.

Feature	Details
Provider-agnostic	Models are specified in `provider:model` format (e.g., `openai:gpt-5.4-nano`)
Structured output	Pydantic models are set as `output_type` for type-safe output
Synchronous execution	`run_sync` is used on Lambda
Streaming	Code generation in des2code runs with streaming
Testing	Agents are mocked via `pydantic_ai.models.test.TestModel`

from pydantic_ai import Agent
from pydantic import BaseModel

class DesignDescription(BaseModel):
    layout: str
    semantic_words: list[str]

agent = Agent(
    "openai:gpt-5.4-nano",    # provider:model format
    output_type=DesignDescription,
    system_prompt="...",
)
result = agent.run_sync(user_prompt)
description: DesignDescription = result.output

Removed from V1: langchain-openai and langgraph.

Embedding Generation

OpenAI Embeddings API (direct SDK call)

Since PydanticAI does not handle embeddings, the openai SDK is called directly.

Item	Value
Model	Configured via `EMBEDDING_MODEL` env var (e.g., `text-embedding-3-small`)
Dimensions	512 (matches DocumentDB HNSW indexes)
Call pattern	Multiple embeddings generated in one batch call (prevents drift)

response = openai_client.embeddings.create(
    model=config.embedding_model,
    input=[visual_text, semantic_text],  # single batch
    dimensions=512,
)
visual_vector = response.data[0].embedding
semantic_vector = response.data[1].embedding

Schema / Validation

Pydantic v2

All SQS inputs, DocumentDB documents, and Webhook payloads are defined as Pydantic models.

from pydantic import BaseModel, Field, model_validator

class CodeImportMessage(BaseModel):
    code_id: str
    organization_id: int
    project_id: int
    source_code: str = Field(..., min_length=1)
    css_code: str | None = None
    img_url: str | None = None

    @model_validator(mode="after")
    def validate_uuid(self) -> "CodeImportMessage":
        uuid.UUID(self.code_id)
        return self

pydantic-settings

Environment variables are validated via BaseSettings. Required variables have no default and fail fast at startup if missing.

from pydantic_settings import BaseSettings

class Config(BaseSettings):
    desc_model: str
    embedding_model: str
    openai_api_key: str
    documentdb_connection_string: str
    webhook_base_url: str

Database

Amazon DocumentDB (MongoDB-compatible)

A vector database dedicated to AI workers. Completely isolated from the PostgreSQL database managed by 4D — AI workers do not access RDS directly.

The planned Page Import and Code2WF workers use S3 artifacts and do not access DocumentDB.

Collection	Write worker	Read worker
`design`	design-import	des2code
`code`	code-import	des2code

HNSW Vector Indexes

Collections use vector indexes for the signals they produce: visual, semantics, structural, and context.

Index	Path	Dimensions	Similarity	Parameters
`visualVectorIndex`	`visual.vector_embedding`	512	cosine	m=16, efConstruction=64
`semanticVectorIndex`	`semantics.vector_embedding`	512	cosine	m=16, efConstruction=64
`structuralVectorIndex`	`structural.vector_embedding`	512	cosine	m=16, efConstruction=64
`contextVectorIndex`	`context.vector_embedding`	512	cosine	m=16, efConstruction=64

structuralVectorIndex applies to design; contextVectorIndex applies to code.

Driver

pymongo is used. The connection string is configured via DOCUMENTDB_CONNECTION_STRING, and the TLS CA is /var/task/global-bundle.pem on Lambda.

AWS Services

Service	Purpose
SQS	Job queues (separate queues for design-import, code-import, des2code)
S3	Fetching design images and code preview screenshots
Lambda	Worker execution environment (SQS-triggered)
DocumentDB	Vector database

Page Import and Code2WF use dedicated SQS queues and DLQs. Page Import stores captured and normalized page artifacts in S3; Code2WF stores a WF2Des-shaped result artifact containing the existing DesignSpecModel in S3.

Partial SQS failures are reported via batchItemFailures so that only failed records are retried.

return {"batchItemFailures": [{"itemIdentifier": record["messageId"]}]}

HTTP Client

httpx

Used for Webhook POST (POST /v1/webhooks/ai-status).

import httpx

httpx.post(
    config.webhook_base_url,
    json=payload,
    headers={"X-API-Key": config.webhook_api_key},
    timeout=10,
)

Logging

loguru

Used for structured logging. print() is forbidden.

from loguru import logger

logger.info("process_record started", code_id=message.code_id, project_id=message.project_id)
logger.error("webhook failed", code_id=message.code_id, status_code=resp.status_code)

Testing

pytest

Test runner.

PydanticAI TestModel

Used to mock PydanticAI agents in tests.

from pydantic_ai.models.test import TestModel

agent = build_vision_agent.__wrapped__(TestModel())

Package Management

uv workspace

Used for monorepo-wide package management. Each app is defined as an independent project via pyproject.toml, and shared packages live in packages/.

Shared Packages

Package	Contents
`packages/agentic`	PydanticAI agent definitions (vision, code_semantics, code_visual, code_gen)
`packages/models`	DocumentDB collection definitions and HNSW index creation
`packages/helpers`	Shared utilities for S3 download, Webhook POST, and embedding generation
`packages/utils`	pydantic-settings base class, DocumentDB connection singleton

Key Changes from V1

V1	V2
LangChain + LangGraph	PydanticAI
Single embedding	Multiple signal embeddings (visual + semantic + structural/context)
Direct MySQL writes	Webhook only (no RDS access)
`PyMySQL`	Removed
`langchain-openai` / `langgraph`	Removed
Mixed `print` / loguru logging	Unified with `loguru`