Skip to content

AGENTS.md

Latest commit

 

History

History
34 lines (27 loc) · 2.87 KB

AGENTS.md

File metadata and controls

34 lines (27 loc) · 2.87 KB

Repository Guidelines

Project Structure & Module Organization

  • app.py composes the public FastAPI surface by mounting the UI at / and the research API under /research.
  • frontend/ hosts the user-facing FastAPI router (main.py), templates in frontend/templates/, and UI assets in frontend/static/; shared landing files live in the root static/.
  • research/ implements the Gemini-backed report engine with routes in research/main.py, client logic in research/gemini_client.py, and shared schemas/settings in research/models.py.
  • Mirror runtime modules in tests/ (for example, tests/test_research.py, tests/frontend/test_routes.py) when adding coverage.

Build, Test, and Development Commands

  • uv venv .venv && source .venv/bin/activate initializes and activates a local virtual environment.
  • uv pip install -e . installs the package in editable mode so live code edits take effect without reinstalling.
  • uvicorn app:app --reload --port 8000 serves the unified experience at http://localhost:8000.
  • uvicorn frontend.main:app --reload and uvicorn research.main:app --reload target the UI or Gemini API independently during focused work.
  • python -m pytest runs the automated suite; add -k <pattern> to scope the run.

Coding Style & Naming Conventions

  • Follow PEP 8 with 4-space indentation and snake_case names for functions, modules, and variables; keep Pydantic models, settings classes, and FastAPI routers in PascalCase.
  • Prefer explicit imports, typed signatures, and reusable dependency helpers as demonstrated in research/models.py and app.py.
  • Co-locate module constants with their usage, such as static directory paths in frontend/main.py, to simplify maintenance.

Testing Guidelines

  • Use pytest fixtures to stub Gemini and HTTP dependencies; favor behavior-first names like test_generate_report_returns_citations.
  • Validate new routes across success and error paths, covering schema enforcement, Gemini fallbacks, and Markdown sanitization before shipping.

Commit & Pull Request Guidelines

  • Keep commits small, scoped, and imperative (e.g., “Improve mobile UI”, “Guard chat prompt”), with subjects under roughly 50 characters.
  • Pull requests should summarize user-facing impact, list verification steps (commands run, screenshots for UI changes), and link relevant issues or research notes.

Security & Configuration Tips

  • Load GOOGLE_API_KEY, GEMINI_MODEL, and GEMINI_TEMPERATURE from .env via pydantic-settings; never commit secrets or sampled responses.
  • Gate outbound requests and experimental toggles in frontend/main.py to safeguard credentials and preview-only features.

Recent Agent Capabilities

  • Gemini-grounded chat ships through /research/chat and GeminiReportGenerator.generate_chat_reply, providing trimmed context, system instructions, and finish-reason handling to the frontend chat UI.