Agent Project Structure

Separate repository (marchay-agent) for all Agent Architecture services. This document defines the repo layout, tech stack, and conventions.

---

Repository Layout

marchay-agent/
├── orchestrator/                # Main service — FastAPI
│   ├── src/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI app, lifespan, health endpoints
│   │   ├── config.py            # Settings via pydantic-settings
│   │   ├── session/
│   │   │   ├── __init__.py
│   │   │   ├── state.py         # SessionState dataclass, serialization
│   │   │   ├── store.py         # Redis + Postgres session store
│   │   │   ├── memory.py        # In-memory LRU cache
│   │   │   ├── reconstruction.py
│   │   │   ├── cleanup.py       # Background TTL cleanup
│   │   │   └── migration.py     # Session migration on failure
│   │   ├── cascade/
│   │   │   ├── __init__.py
│   │   │   ├── tools.py         # Tool interface contract + Tier 1/2/3 impls
│   │   │   └── orchestrator.py  # Cascade runner
│   │   ├── llm/
│   │   │   ├── __init__.py
│   │   │   ├── decompose.py     # Decompose step
│   │   │   ├── synthesize.py    # Synthesize step
│   │   │   └── prompts.py       # System prompts
│   │   ├── queue/
│   │   │   ├── __init__.py
│   │   │   ├── producer.py      # Job enqueue (LPUSH)
│   │   │   └── consumer.py      # Result listener (BRPOP)
│   │   ├── routing/
│   │   │   ├── __init__.py
│   │   │   └── sticky.py        # Consistent hash ring
│   │   └── metrics/
│   │       ├── __init__.py
│   │       └── session_metrics.py
│   ├── tests/
│   │   ├── __init__.py
│   │   ├── conftest.py
│   │   ├── test_state.py
│   │   ├── test_memory.py
│   │   ├── test_store.py
│   │   ├── test_reconstruction.py
│   │   └── test_sticky.py
│   ├── alembic/
│   │   ├── alembic.ini
│   │   └── versions/
│   ├── pyproject.toml
│   ├── Dockerfile
│   └── README.md
│
├── agents/                      # Per-vertical research agents
│   ├── dining/
│   │   ├── src/
│   │   ├── tests/
│   │   └── pyproject.toml
│   ├── experiences/
│   ├── transportation/
│   ├── flights/
│   └── dmc/
│
├── shared/                      # Common schemas and queue client
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── job.py               # Job payload schema
│   │   ├── result.py            # Result schema
│   │   └── member.py            # Member, Trip shared types
│   ├── queue/
│   │   ├── __init__.py
│   │   └── client.py            # Redis queue client
│   └── pyproject.toml
│
├── docker-compose.yml           # Local dev: Redis, Postgres
├── Makefile                     # Common commands
├── .gitlab-ci.yml               # CI/CD pipeline
└── README.md

---

Tech Stack

Component	Choice	Rationale
Language	Python 3.12+	Proven in spike, LangChain ecosystem
Framework	FastAPI	Async, WebSocket support, auto-docs
Session Store (fast)	Redis 7	Sub-ms reads, TTL, pub/sub
Session Store (persistent)	PostgreSQL 16	ACID, JSONB for preferences
In-Memory Cache	dict + LRU	Fastest path for hot sessions
Queue	Redis (Valkey fork)	Already provisioned, LPUSH/BRPOP
Migrations	Alembic	Standard for Postgres + Python
Testing	pytest + pytest-asyncio	Async test support
Observability	Prometheus client	Metrics endpoint
Linting	ruff	Fast, comprehensive
Type Checking	mypy (strict)	Catch errors early

---

Naming Conventions

• Python: snake_case for files, functions, variables. PascalCase for classes.
• Files: session_state.py, store.py, test_store.py
• Tables: snake_case plural (sessions, conversation_history)
• Redis keys: session:{session_id}, jobs:{agent_type}, result:{job_id}
• Metrics: orchestrator_session_active, orchestrator_session_reconstructed_total
• Git branches: feat/session-state, fix/redis-timeout, chore/update-deps

---

Repo Relationship

This repo (marchay-agent) is separate from the architecture docs repo (marchay-docs).

Repo	Purpose	Contents
marchay-docs	Architecture planning	Design docs, build briefs, roadmaps
marchay-agent	Production code	Orchestrator, agents, shared libs

The build brief in marchay-docs serves as the spec. Implementation lives in marchay-agent.

---

Makefile

.PHONY: dev test lint typecheck migrate

dev:
	docker compose up -d
	cd orchestrator && uvicorn src.main:app --reload --port 8000

test:
	cd orchestrator && pytest tests/ -v --cov=src --cov-report=term-missing

lint:
	ruff check orchestrator/ agents/ shared/

typecheck:
	mypy orchestrator/src/

migrate:
	cd orchestrator && alembic upgrade head

build:
	docker compose build

prod:
	docker compose -f docker-compose.prod.yml up -d