Portfolio Intelligence Assistant

AI-powered portfolio analysis platform.

Users upload their portfolios (PDF, CSV, Excel) and the system produces comprehensive analysis using a LangGraph-based 10-agent AI pipeline and 15+ Python financial engines. All numerical computations run on deterministic Python engines — zero hallucination risk. The LLM only interprets the results.

---

Features

Category	Feature
AI Pipeline	LangGraph 10-agent StateGraph (Controller → Planning → Execution → Quality → Decision)
Financial Engines	Risk (VaR, CVaR, Sharpe), Monte Carlo, Optimization (Markowitz), Technical (RSI, MACD), Fundamental (PE, ROE)
RAG	Hybrid retrieval (dense vector + keyword) across portfolio documents with ChromaDB + configurable embeddings
Live Data	TwelveData API (market prices), Tavily API (news sentiment analysis)
Security	Prompt injection protection, rate limiting, file size limits, temporary file cleanup
Dual LLM	Real-time switching between DeepSeek (Cloud) and Ollama (Local)
Dashboard	Next.js + TailwindCSS dark theme, Recharts charts, SSE live streaming
Docker	PostgreSQL + Redis + ChromaDB + NGINX — single command startup
Multilingual	Turkish and English language support
Reports	PDF/Excel report generation

---

Architecture

Browser (:3000) → Next.js → NGINX (:80) → FastAPI (:8001)
                                              ├── LangGraph 10-Agent Pipeline
                                              │   ├── Controller (Intent Detection)
                                              │   ├── Dynamic Router (5 routes)
                                              │   ├── Planning (LLM analysis plan)
                                              │   ├── Execution Layer (15+ Python engines)
                                              │   ├── Auto Summary (LLM natural language)
                                              │   ├── Reflection + Critic (deterministic QA — no agent loops)
                                              │   ├── Decision + Confidence (Decision Layer)
                                              │   └── Missing Info (Gap Detection)
                                              ├── ChromaDB (RAG vector search)
                                              ├── PostgreSQL (persistent storage)
                                              ├── Redis (caching)
                                              └── TwelveData / Tavily / DeepSeek API

Implementation note: the Reflection and Critic nodes run as deterministic pass-through checks — the graph always proceeds forward and never loops. Loop-based agent behavior is intentionally disabled in production for cost and safety. The version string is sourced from app/__init__.py (__version__). Python dependencies are split into profiles: requirements.txt (core), requirements.local-llm.txt (Ollama/PEFT) and requirements.gpu.txt (CUDA). Hybrid RAG retrieval is exposed through VectorStoreService.hybrid_search.

---

Quick Start

Docker (recommended)

# Start all services (API + PostgreSQL + Redis + NGINX)
docker compose up -d

# Start frontend
cd frontend
npm install
npm run dev

→ Backend: http://localhost:8001/docs → Frontend: http://localhost:3000

Manual Setup

Requirements

• Python 3.12+
• Node.js 18+
• Ollama (optional, for local LLM)

Backend

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env   # Enter your API keys in the .env file
python app/main.py

Frontend

cd frontend
npm install
npm run dev

Local LLM (Optional)

ollama pull llama3.2
ollama pull qwen2.5

---

Environment Variables

Copy backend/.env.example to .env:

Variable	Description
DEEPSEEK_API_KEY	DeepSeek API key
TWELVEDATA_API_KEY	TwelveData live market data
TAVILY_API_KEY	Tavily news search
LANGSMITH_API_KEY	LangSmith tracing (optional)
OLLAMA_BASE_URL	Ollama server URL (default: http://localhost:11434)

---

API Endpoints

Method	Endpoint	Description
GET	/	Health check
POST	/api/upload	Upload portfolio file (PDF/CSV/Excel)
POST	/api/chat	AI chat — LangGraph pipeline
POST	/api/analyze	Full SSE analysis (14-stage streaming)
POST	/api/dashboard	Dashboard data
POST	/api/onboarding/questions	Investor profile questions
POST	/api/generate-report	Download PDF/Excel report
GET	/api/portfolio/{id}	Portfolio metadata
DELETE	/api/portfolio/{id}	Delete portfolio

---

Project Structure

portfolio_intelligence_assistant/
├── backend/
│   ├── app/
│   │   ├── api/              # FastAPI endpoints
│   │   ├── graph/            # LangGraph 10-agent pipeline
│   │   │   ├── nodes/        # Agent nodes
│   │   │   └── routers/      # Dynamic routing
│   │   ├── engines/          # 15+ Python financial engines
│   │   ├── services/         # Parser, RAG, reports, cache, auth
│   │   ├── config/           # Settings, feature flags, LLM registry
│   │   ├── core/             # LLM factory, security
│   │   └── db/               # SQLAlchemy models
│   ├── tests/                # Unit / Integration / E2E tests
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js pages (landing, dashboard)
│   │   ├── components/       # Upload, Chat, Charts, Dashboard
│   │   ├── services/         # API service layer
│   │   └── types/            # TypeScript interfaces
│   └── package.json
├── docker-compose.yml        # Development environment
├── docker-compose.prod.yml   # Production environment
├── nginx.conf                # NGINX reverse proxy
├── prometheus.yml            # Prometheus monitoring
├── ARCHITECTURE.md           # Detailed technical architecture
└── .github/workflows/ci.yml  # CI/CD pipeline

---

Tests

cd backend
pytest tests/ --cov=app --cov-report=term -v

CI/CD pipeline: Automated test + lint + Docker build on every push. Details: .github/workflows/ci.yml