Imported from JawandS/daily-brief (AGENTS.md). Install upstream with npx skills add JawandS/daily-brief. Copyright stays with the author.

Repository Guidelines

Name: daily-brief
Author: JawandS

Project Structure & Module Organization

app/ contains the FastAPI application.
app/briefs/ implements brief generators (research.py, postmortem.py, news.py) built on app/briefs/base.py.
app/sources/ handles data ingestion (ArXiv, RSS, and news search).
app/llm/ contains model integrations; Gemini handles scoring/summarization and Claude handles refinement/narrative.
app/dashboard/ provides HTMX-backed routes and Jinja templates for the web UI.
app/email/ manages email rendering and sending.
scripts/run_brief.py is the manual/cron entry point.
context/ stores prompt context files used during brief generation.

uv sync: install dependencies into the project virtual environment.
uv run uvicorn app.main:app --reload: run the dashboard locally.
uv run python -m scripts.run_brief: run all briefs and send email.
uv run python -m scripts.run_brief --preview: run generation without sending email (preferred for validation).

Use Python 3.11+ conventions with 4-space indentation and type hints where useful.
Keep modules focused by domain (briefs, sources, llm, email, dashboard).
Use snake_case for functions/variables/files and PascalCase for classes/data models.
Keep route handlers async in FastAPI modules.
Follow existing concise docstring/comment style; only add comments where behavior is non-obvious.

There is currently no dedicated automated test suite in this repository.
Validate behavior with uv run python -m scripts.run_brief --preview and dashboard checks (/ and /health).
When adding tests, prefer pytest under tests/ with files named test_<module>.py and focused unit coverage for briefs and sources.

Current history favors short, imperative commit subjects (for example: fix start command, redesign news service).
Keep commit messages specific to one change and avoid mixing refactors with behavior changes.
PRs should include: purpose, key files changed, validation steps/commands run, and screenshots for dashboard template/UI updates.

Required environment variables: GEMINI_API_KEY, ANTHROPIC_API_KEY, RESEND_API_KEY.
Never commit secrets or .env files.
Use preview mode for development to avoid unintended email sends.