AI Investment Advisor

     

English | 繁體中文 | 日本語

---

You just put $10,000 into a brokerage. How do you decide what to buy, when to hedge, and when to exit?

AI Investment Advisor is an autonomous quantitative platform that deploys a 7-Agent Swarm powered by Fractal Debate — a multi-round adversarial reasoning framework that eliminates single-model hallucinations. A CIO Agent decomposes investment questions, delegates to domain experts, orchestrates debate, and executes trades automatically via eToro's API.

Debates that converge > predictions that hallucinate.

---

✨ Features

🧬 Fractal Debate Multi-agent adversarial reasoning across 7 specialized agents. Eliminates single-model hallucinations through structured disagreement and convergence.	🦅 10-Dimension Sentinel VIX, price, news, macro, allocation drift — autonomous risk radar that never sleeps. Auto-triggers hedging and rebalancing.
⚡ Auto-Hedging Millisecond-precision position liquidation via eToro API. Dual-track webhooks for rapid emergency response during market crashes.	🧠 OpenClaw Architecture Per-agent WAL (Write-Ahead Logging) with independent workspaces. Eliminates context overflow amnesia in long financial analyses.
📊 Hybrid RAG BM25 + temporal-decay semantic search via pgvector + Redis. Decisions are grounded in deep historical context, not just recent data.	🔐 Enterprise-Grade Security Fernet encryption at rest, parameterized SQL only, hardened Docker images, and SHA256 signal verification.
📡 Full Observability OpenTelemetry 1.39 + SigNoz APM. Distributed traces, metrics, and logs across all agents and services.	🔄 Scheduled Workflows Celery Beat orchestrates daily checks, weekly reports, and sentinel ticks. Set it and forget it.

---

🏗️ Architecture

graph TD
    User((User)) <-->|Dashboard| FE["Next.js Frontend"]
    FE <-->|REST API| API["FastAPI + MCP Server"]

    subgraph "🧠 Intelligent Core"
        API --> WF["WorkflowService"]
        WF --> CIO["CIO Agent"]
        CIO -->|Decompose| SUB["7 Sub-Agents"]
        SUB -->|Fractal Debate| COUNCIL{"Council"}
        COUNCIL --> ENG["Engineer Agent"]
        SENT["Sentinel 🦅"] -->|Triggers| SA["SentinelAgent"]
        SA --> COUNCIL
    end

    subgraph "💾 Data & Memory"
        PG["PostgreSQL + pgvector"]
        RD["Redis Cache"]
    end

    subgraph "⚡ Execution"
        TRADE["AutomatedTradingService"]
    end

    COUNCIL -->|Actions| TRADE
    CIO <--> PG
    CIO <--> RD

3-Tier LLM Routing

Tier	Purpose	Example Models
Advanced 🚀	Deep analysis, CIO decisions	GPT-4o, Claude 3.5 Sonnet
Smart 🧠	Debate, reasoning, classification	Gemini 1.5 Pro
Fast ⚡	Formatting, screening, extraction	GPT-4o-mini, Ollama local

3-Tier Data Storage

Tier	Engine	Use Case
Hot 🔥	Redis	Semantic cache, real-time state
Warm ☀️	PostgreSQL + pgvector	Structured records, vector search
Cold ❄️	File System	Raw reports, historical backtests

---

🛠️ Tech Stack

Category	Technology
Language	Python 3.11, TypeScript
Backend	FastAPI, MCP (Model Context Protocol), Celery
Frontend	Next.js 15 (App Router), Streamlit (legacy)
AI/ML	LiteLLM, DSPy, OpenAI / Gemini / Claude / Ollama multi-provider
Database	PostgreSQL 16 + pgvector, Redis, SQLite (dev)
Infra	Docker Compose, Nginx, SigNoz, OpenTelemetry 1.39
Trading	eToro API (automated fractional trading)
Data Sources	Polygon, Tiingo, Finnhub, AlphaVantage, FMP, FRED, TAVILY
Notifications	Telegram, LINE, Email (SMTP)

---

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.10+ (for local development)
• Node.js 20+ (for frontend development)

Launch (self-host, one command)

git clone https://github.com/neohsiung/AI-Investment-Advisor.git
cd AI-Investment-Advisor
./start.sh selfhost

This auto-generates every required secret, defaults to paper trading mode (no real orders, ever, until you opt in), builds and starts the full stack, and applies database migrations. See docs/SELF_HOSTING.md for the first-run LLM provider setup, cost expectations, and how to switch to live trading when you're ready.

For local development instead of the hardened self-host profile, use ./start.sh dev (includes SigNoz APM, n8n, and debugging tools).

Service	URL
Gateway (nginx, prod only)	http://127.0.0.1:8088
Next.js Dashboard	http://localhost:3001
FastAPI / MCP Server	http://localhost:8000 (dev: 8001)
SigNoz APM	http://127.0.0.1:8080

The dev stack's nginx publishes no host port — reach the frontend and API directly on the ports above. The gateway exists in production only.

---

📁 Project Structure

AI-Investment-Advisor/
├── .agent/              # Agent governance layer (rules, skills, workflows)
│   ├── rules/           #   Coding, testing, security, commit standards
│   ├── skills/          #   15 specialized capability packages
│   └── workflows/       #   Operational playbooks
├── alembic/             # Database migrations (PostgreSQL)
├── config/              # Model routing, LLM seed data, persona definitions
├── deployment/          # Helm charts, PostgreSQL manifests
├── frontend/            # Next.js 15 dashboard (TypeScript)
├── infra/               # Nginx reverse proxy, SigNoz observability config
├── k8s/                 # Kubernetes manifests (future deployment)
├── prompts/             # Agent system prompts (CIO, Sentinel, sub-agents)
├── scripts/             # Ops: DB seed, deployment, health checks
├── services/            # Microservice entrypoints
│   ├── mcp_server/      #   FastAPI + MCP server (main backend)
│   ├── notification/    #   Telegram / LINE / Email service
│   ├── scheduler/       #   Celery Beat scheduler
│   └── dashboard/       #   Streamlit dashboard (legacy)
├── src/                 # Core Python package
│   ├── agents/          #   Agent definitions + skills (eToro trade, research)
│   ├── api/             #   FastAPI route handlers
│   ├── config/          #   App configuration, data source matrix
│   ├── domain/          #   Domain models
│   ├── infrastructure/  #   Celery, LLM gateway, OTel instrumentation
│   ├── repositories/    #   Database access (ORM + raw SQL)
│   ├── services/        #   Business logic services
│   └── workflow/        #   Daily / weekly workflow orchestrators
├── tests/               # Unit, integration, e2e tests
├── workspace/           # Multi-agent workspace (WAL, identity, memory)
├── AGENTS.md            # AI coding assistant context (unified standard)
├── CHANGELOG.md         # Version history (Keep a Changelog format)
├── SECURITY.md          # Security policy & vulnerability reporting
├── docker-compose.yml   # Development stack
├── docker-compose.prod.yml  # Production stack
├── pyproject.toml       # Python project config & dependencies
└── start.sh             # One-command full-stack launcher

---

🤖 AI Agent Context

This project uses AGENTS.md as the unified context file for all AI coding assistants (Antigravity, Claude Code, Cursor, Copilot, Gemini CLI). It provides:

• Project identity and architecture overview
• Key technical constraints and conventions
• Build, test, and lint commands
• Directory semantics and documentation references

For deeper governance rules, skills, and workflows, see the .agent/ directory.

---

📏 Governance & Standards

Standard	File
Engineering & coding	.agent/rules/engineering-standards.md
Git commit format	.agent/rules/git-commit-format.md
Documentation	.agent/rules/documentation-standards.md
Observability	.agent/rules/observability-standards.md
Security policy	SECURITY.md

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run the tests (pytest tests/ -x --tb=short)
4. Commit your changes and open a pull request

Please open an issue first for major changes so we can discuss the approach.

---

📚 Documentation

• 📖 Full Wiki: See the Wiki for architectural blueprints, data source matrix, and contribution guides.
• 📝 Changelog: See CHANGELOG.md for version history.

---

Star History

---

📄 License & Disclaimer

• License: Apache License 2.0
• Disclaimer: This project autonomously analyzes markets and, if configured with live broker credentials, can place real trades with real money. It is not financial advice, provided "AS IS" with no warranty. See NOTICE for the full disclaimer.

---

Stop guessing. Start debating. Let agents converge on truth.

Apache License 2.0 © AI Investment Advisor Contributors