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. For the normal CLI path, set GOOGLE_API_KEY, FINNHUB_API_KEY, and TAVILY_API_KEY. For better international data or optional consultant paths, add keys such as EODHD, FMP, or OpenAI where your workflow needs them. The exact knobs live in .env.example.

Run a fast smoke test (you can use a ticker other than 7203.T, if you want):

poetry run python -m src.main --ticker 7203.T --quick --output results/7203.T.md

That command exercises the main runtime and writes a markdown report. Saved analysis JSONs in results/ also, optionally, power portfolio_manager.py and the dashboard later.

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 RPM settings in .env make sense.

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