Skip to content

About

Typed portfolio-analysis agent with FastAPI, React, LangChain tools, and response verification.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

36 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ghostfolio Agent

CI Python 3.11+ License: MIT

Ghostfolio Agent is a portfolio-analysis assistant built around typed tools and response checks. It can summarize holdings, assess concentration risk, retrieve market data, categorize transactions, and run compliance rules. The repository contains a FastAPI service and a React application.

The previous Railway deployment has been removed. Follow the deployment guide to create a new instance.

What it includes

  • Seven LangChain tools for portfolio analysis, risk, market data, transaction categorization, compliance, price history, and cryptocurrency trends
  • A verification pipeline with confidence scores, constraint checks, fact checks, and escalation signals
  • Evaluation cases for normal, edge, and adversarial requests
  • Session history, usage tracking, feedback records, and optional LangSmith traces
  • A React interface for portfolio chat, repository analysis, tool management, evaluations, and cost review

Architecture

React application
      |
      | /api/*
      v
FastAPI service
      |
      +-- Ghostfolio client
      +-- market-data clients
      +-- LangGraph agent and tools
      +-- verification and evaluations

The frontend sends /api/* requests to Nginx. Nginx reads BACKEND_URL when the container starts and proxies those requests to FastAPI.

Run with Docker

Requirements: Docker and Docker Compose.

cp .env.example .env

Set OPENAI_API_KEY and a random API_ACCESS_TOKEN of at least 32 characters in .env. Generate the owner token with python -c "import secrets; print(secrets.token_urlsafe(32))". Enter that token in the frontend sign-in form. Leave USE_MOCK_DATA=true if you do not have a Ghostfolio instance.

This application supports one trusted owner per deployment. All private API routes (including documentation and administrative operations) require Authorization: Bearer <API_ACCESS_TOKEN>. Only /health and CORS preflight are public; an unconfigured token returns 503 on protected routes. Do not share the owner token between unrelated users. Run one backend worker; request limits and session serialization are process-local. Multi-user or multi-worker deployments require a shared authorization, rate-limit, and persistence layer.

docker compose up --build

Open:

  • React application: http://localhost:3000
  • FastAPI documentation: http://localhost:8000/docs
  • Backend health check: http://localhost:8000/health

Run without Docker

Backend

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
uvicorn src.api.routes:app --reload --port 8002

On Windows, activate the environment with .venv\Scripts\activate. Configure .env and the owner token as described above before using the API or frontend.

Frontend

cd frontend
npm ci
npm run dev

Open http://localhost:5173. Vite proxies /api to http://localhost:8002.

Connect Ghostfolio

Set these variables in .env:

USE_MOCK_DATA=false
GHOSTFOLIO_API_URL=http://localhost:3333
GHOSTFOLIO_ACCESS_TOKEN=replace_with_your_token

Create the access token in Ghostfolio under Settings > Security. Keep the token on the backend. Do not put it in the React application or commit it to Git.

Main API routes

Route Purpose
GET /health Service and dependency status
POST /chat Run an agent request
GET /portfolio Portfolio summary
GET /portfolio/risk Concentration and risk analysis
GET /market/{symbol} Market-data lookup
GET /tools Available tools
POST /evals/run Run evaluation cases
GET /traces Stored trace records

See the interactive FastAPI documentation at /docs for the full API.

Test and build

The outcome evaluation harness adds versioned synthetic financial scenarios, mutation-tested graders, and reproducible paired experiments:

python -m evals.benchmark --repetitions 5 --require-candidate-pass --fail-on-regression

The default comparison is explicitly an offline policy demonstration. Real model comparisons require configured model identifiers and --allow-paid. Reports keep per-scenario outcomes, errors, traces, uncertainty, source/data hashes, and unknown costs distinct. See the recorded offline comparison for a complete example with per-scenario results and failure evidence. The real-model comparison notes include observed OpenRouter free-model runs, the issues they uncovered, and the final repeated baseline/candidate results. The comparison reports distinguish verified financial outcomes from optional-output adherence and preserve original failures.

Backend:

python -m pytest -q
python -m ruff check src tests --select E9,F63,F7,F82

Frontend:

cd frontend
npm ci
npm audit --omit=dev --audit-level=high
npm run lint
npm test
npm run build

The CI workflow runs these checks and builds both Docker images.

Configuration

Variable Required Purpose
OPENAI_API_KEY Yes Model requests
USE_MOCK_DATA No Use local sample portfolio data
GHOSTFOLIO_API_URL For live data Ghostfolio server URL
GHOSTFOLIO_ACCESS_TOKEN For live data Server-side Ghostfolio token
LANGSMITH_API_KEY No LangSmith traces
COINGECKO_API_KEY No Higher CoinGecko rate limits
API_ACCESS_TOKEN Yes Random single-owner bearer token, at least 32 characters
REPO_ALLOWED_ROOTS No Allowed local repository roots; empty disables local attachment
GENERATED_TOOL_EXECUTION_ENABLED No Opt into isolated Docker tool execution; default false
CORS_ORIGINS Production Comma-separated frontend origins
BACKEND_URL Frontend container FastAPI URL used by Nginx

The complete list and local defaults are in .env.example.

Live market-data failures return explicit errors; synthetic data is only available in mock mode and is labeled is_mock. Verification confidence is heuristic and is null when scoring is disabled. Disabling human review preserves detected warnings but does not request escalation. Evaluation requests return completed after finishing, and unmeasured hallucination rates remain null.

Local repository reads reject hidden/secret files, symlinks, path escapes, and oversized files even inside allowed roots. Generated Python is never imported into the API process. See the security and verification changes for sandbox setup and regression coverage.

Deployment

See docs/DEPLOYMENT.md for the two-service Railway configuration and post-deployment checks.

License

MIT. See LICENSE.

About

Typed portfolio-analysis agent with FastAPI, React, LangChain tools, and response verification.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages