Repository Guidelines

This repo hosts a FastAPI + React demo where a supervisor LLM orchestrates worker agents. Use this guide to contribute consistently and safely.

Project Structure & Module Organization

• main.py: Entrypoint that imports the FastAPI app.
• app/: Package with modules:
  • server.py: FastAPI wiring and routes.
  • registry.py: Agent definitions and lookup helpers.
  • planner.py: LLM planner with fallback plan.
  • agent_caller.py: Handshake builder and HTTP agent calls (returns structured errors if endpoints/httpx fail).
  • executor.py: Plan execution and input resolution.
  • answer.py: Final answer synthesis (LLM + fallback).
  • models.py: Shared Pydantic schemas.
  • web.py: React UI served from /.

Build, Test, and Development Commands

• uvicorn main:app --reload — run the dev server at http://localhost:8000.
• python main.py — convenience entrypoint; proxies to uvicorn with reload.
• pytest (add later) — preferred for automated tests; use httpx.AsyncClient + FastAPI TestClient for API tests.

Coding Style & Naming Conventions

• Python 3.10+; prefer type hints and Pydantic models for all contracts.
• Indent with 4 spaces; keep lines reasonably short and comments succinct.
• Function names: snake_case; classes: PascalCase; registry agent names: snake_case_agent.
• UI uses React (CDN + Babel). Keep components small; co-locate UI tweaks in web.py.

Testing Guidelines

• Add unit tests for planner fallbacks, registry lookups, and /api/query happy-path/error cases.
• When stubbing agents, assert handshake shape (request_id, status, output/error).
• Include at least one test that exercises the debug payload structure (used_agents, intermediate_results).

Commit & Pull Request Guidelines

• Commit messages: imperative mood (e.g., "Add planner fallback when OpenAI missing").
• PRs: describe scope, risks, and how you tested; attach screenshots of the UI if changed.
• Keep PRs small and scoped; call out breaking changes and required env vars (e.g., OPENAI_API_KEY).

Security & Configuration

• Secrets: never commit; rely on environment variables (OPENAI_API_KEY).
• Networked agents: validate endpoints before enabling real HTTP calls. Timeouts are set per agent; keep them conservative.
• If adding persistent storage, document schema and migration steps before merging.