ai-investment-agent Agent工作流

Quick Start

I am assuming here that you have worked with Git repositories, feel comfortable at a command prompt, and understand basic things like what an exchange and stock ticker are.

git clone https://github.com/rgoerwit/ai-investment-agent.git
cd ai-investment-agent

poetry install
cp .env.example .env

Edit .env next. FINNHUB_API_KEY and TAVILY_API_KEY are always required. GOOGLE_API_KEY is required for the shipped default bindings, and startup derives that from the binding plan rather than assuming it — a configuration with no seat bound to Google does not demand one. Add a provider key for each group you bind (OPENAI_API_KEY, ANTHROPIC_API_KEY, MOONSHOT_API_KEY, DEEPSEEK_API_KEY, ZAI_API_KEY), plus EODHD or FMP for better international data. The exact knobs live in .env.example.

End-to-end path: scrape configured exchanges, filter, quick-screen, then run

Optional Safety, Cross-Checks, and Tracing

These features matter, but they are supporting infrastructure. You do not need them for the first successful run.

For the broader local threat model, including secrets, broker context, untrusted content, MCP, and OWASP LLM Top 10 coverage, read SECURITY.md.

Advanced Topics and References

These are real features, but they are not required to get started:

• Agentic AI background: docs/AGENTIC-AI-101.md explains the broader agentic-AI ideas behind the repo without making this README carry that whole discussion.
• Security model: SECURITY.md summarizes the local threat model, untrusted-content inspection, broker/dashboard cautions, and OWASP LLM Top 10 alignment.
• Container mode: the repo includes a Dockerfile and supports local bind-mounted runs. Prefer Podman if you want stronger workstation isolation.
• Observability: Langfuse and LangSmith hooks exist for tracing and diagnostics. For sensitive deployments, LangSmith also supports LANGSMITH_HIDE_INPUTS and LANGSMITH_HIDE_OUTPUTS.
• Inspection and tool audit hooks: see src/tooling/ if you want to inspect or audit untrusted external content before it reaches LLM context.
• Deployment references: terraform/ contains reference infrastructure, not a turnkey hosted product.

Choose Your Workflow

• Analyze one ticker: use poetry run python -m src.main --ticker ...
• Screen a broader universe: use scripts/run_pipeline.sh
• Reconcile a portfolio afterwards: use scripts/portfolio_manager.py
• Use the browser UI: run python -m src.web.ibkr_dashboard.app, and start the worker only if you want queued refresh jobs

Screening Pipeline

The screening pipeline is the shortest path from broad discovery to a shortlist of full reports.

```bash

Step-by-step alternative

poetry run python scripts/find_gems.py --output scratch/gems.txt

Troubleshooting

Poetry or import issues

poetry env remove --all
poetry install

If ./scripts/run_pipeline.sh or another script unexpectedly uses plain python, check whether you have an unrelated virtual environment active. The pipeline falls back to Poetry when the active venv is missing core repo dependencies, but the cleanest fix is one of:

deactivate
poetry install
poetry run python -m src.main --ticker 0005.HK

If poetry run ibkr-dashboard or poetry run ibkr-dashboard-worker warns that the entry point "isn't installed as a script", the commands were added to pyproject.toml after the virtualenv was created, or the project root was not reinstalled. poetry install fixes that. As a fallback, run:

poetry run python -m src.web.ibkr_dashboard.app
poetry run python -m src.web.ibkr_dashboard.worker

Python version mismatch

• This repo expects Python 3.12.x.
• Check with python --version and make sure Poetry is using the same interpreter.

API errors or quota issues

• Check .env first.
• Free-tier Gemini works, but rate limits and retries are normal.
• If you have a paid tier, make sure the API key belongs to the right project and that your per-provider RPM ceilings (GOOGLE_RPM_LIMIT, OPENAI_RPM_LIMIT, ANTHROPIC_RPM_LIMIT, DEEPSEEK_RPM_LIMIT, ZAI_RPM_LIMIT, MOONSHOT_RPM_LIMIT, XAI_RPM_LIMIT) match the account's real quota. Each provider gets an independent bucket, so raising one does not affect the others.

LLM binding configuration errors at startup

Binding problems fail before any model is built, listing every problem at once rather than one per run. The message names the seat and the setting; the common ones:

To see what a configuration actually resolves to without running an analysis, read the binding telemetry from any saved artifact:

jq -r '.run_summary.llm_bindings.seats | to_entries[] | select(.value.enabled)
       | "\(.key)\t\(.value.vendor)/\(.value.model)"' results/<TICKER>_<STAMP>_analysis.json

portfolio_manager.py or analysis index rebuild is unexpectedly slow on macOS

Spotlight indexing on .venv/ or results/ can turn a normal index rebuild into a very slow one.

touch .venv/.metadata_never_index results/.metadata_never_index