Imported from Tayne78/finsight-agent (AGENTS.md). Install upstream with npx skills add Tayne78/finsight-agent. Copyright stays with the author.

AGENTS.md

This file is for AI coding agents working in this repository. Read this first and keep context usage low by following the entry points below.

Mission

Build and evolve a reliable FastAPI backend for FinSight Agent:

• accept a company name and ticker from a frontend
• collect market data and recent news
• coordinate specialist research agents and a supervisor agent with Amazon Bedrock
• return JSON and PDF outputs

First Files To Read

Only read these files first unless the task requires more:

1. README.md
2. backend/app/main.py
3. backend/app/schemas/analysis.py
4. backend/app/agents/orchestrator.py
5. frontend/src/api/finsight.js if the task touches frontend/backend integration
6. the specific file you need to change

Do not load the whole repo by default.

Local Dev Entry Points

Use these scripts instead of retyping setup commands:

• ./scripts/dev_setup.sh
• ./scripts/dev_backend.sh
• ./scripts/dev_frontend.sh

Port overrides:

• PORT=8010 ./scripts/dev_backend.sh
• FRONTEND_PORT=5174 ./scripts/dev_frontend.sh

Architectural Boundaries

Keep these boundaries stable:

• backend/app/main.py Route registration and HTTP concerns only.
• backend/app/schemas/ Pydantic input/output contracts.
• backend/app/agents/ Orchestration and report assembly flow. Specialist agents run in parallel via ThreadPoolExecutor.
• backend/app/tools/ Data fetching from external sources such as finance APIs or search.
• backend/app/services/ Provider integrations and rendering, such as Bedrock and PDF generation.

Do not mix these concerns unless there is a clear refactor plan.

Current Flow

/analyze and /analyze/pdf call app.agents.orchestrator.run_analysis().

run_analysis() currently:

1. collects metrics from app.tools.finance_tools
2. collects headlines from app.tools.search_tools
3. runs 4 specialist agents (news, fundamentals, risk, comparison) in parallel via ThreadPoolExecutor
4. sends their outputs to the supervisor agent
5. returns a normalized report dictionary

/analyze/pdf additionally passes that dictionary to services.pdf_service.

Rules For New Work

1. Keep route handlers thin.
2. When adding response fields, update backend/app/schemas/analysis.py first.
3. When adding a new data source, place the fetch logic in backend/app/tools/ or a dedicated backend/app/services/ module.
4. When Bedrock prompt logic becomes large, move prompts into dedicated constants or a prompts/ package.
5. Prefer additive changes over broad rewrites during the hackathon window.
6. Preserve backward compatibility for /analyze unless the API contract is intentionally changed.

Preferred Growth Path

Add modules in this order when complexity increases:

1. backend/app/services/analysis_service.py
2. backend/tests/
3. backend/app/prompts/
4. frontend/src/pages/

Only add these once the current multi-agent scaffold becomes a real bottleneck.

Bedrock Implementation Notes

• Bedrock access is environment-driven through backend/app/config.py which loads backend/.env.
• Validate credentials and model access before changing prompts.
• If a model call fails, inspect region, model ID, and access permissions first.
• Keep prompt outputs machine-parseable.

PDF Output Rules

• PDF generation must remain deterministic from the analysis result dictionary.
• Do not let PDF code fetch data or call Bedrock.
• Keep presentation logic in backend/app/services/pdf_service.py.

Frontend Contract

The frontend should only need:

• GET /health
• POST /analyze
• POST /analyze/pdf

Avoid forcing frontend changes unless necessary for product value.

Hackathon Constraints

Optimize for:

• reliable end-to-end demo flow
• clear Amazon Nova usage
• visible specialist-agent collaboration
• clean architecture judges can understand quickly

Avoid:

• unnecessary infra complexity
• premature microservices
• large refactors close to demo time

If You Need More Structure

Use this decision rule:

• new HTTP shape -> backend/app/schemas/
• new report assembly logic -> backend/app/agents/
• new external fetcher -> backend/app/tools/
• new provider or renderer -> backend/app/services/

If a change does not fit one of these buckets, document why before introducing a new top-level directory.