https://github.com/aymanyaq/cairniq
Local-first AI portfolio intelligence console for personal market research, portfolio monitoring, and risk-aware decision support.
https://github.com/aymanyaq/cairniq
ai ai-agent anthropic claude fastapi finance financial-advisor fintech investing langgraph llm market-analysis multi-agent portfolio portfolio-management python stock-market wealth-management
Last synced: about 6 hours ago
JSON representation
Local-first AI portfolio intelligence console for personal market research, portfolio monitoring, and risk-aware decision support.
- Host: GitHub
- URL: https://github.com/aymanyaq/cairniq
- Owner: aymanyaq
- License: other
- Created: 2026-06-20T02:34:39.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2026-06-29T22:12:14.000Z (5 days ago)
- Last Synced: 2026-06-30T00:03:30.099Z (5 days ago)
- Topics: ai, ai-agent, anthropic, claude, fastapi, finance, financial-advisor, fintech, investing, langgraph, llm, market-analysis, multi-agent, portfolio, portfolio-management, python, stock-market, wealth-management
- Language: Python
- Homepage: https://www.cairniq.com
- Size: 2.89 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# CairnIQ
CairnIQ is a local-first AI portfolio intelligence console for personal market research, portfolio monitoring, and risk-aware decision support.
🌐 **Official Website:** [cairniq.com](https://www.cairniq.com)
> [!CAUTION]
> **NOT FINANCIAL ADVICE**: This software is for educational and informational purposes only. Trading involves significant risk. The authors and contributors assume no liability for financial losses. Never make investment decisions based solely on this tool. Always consult with a certified financial advisor.
> [!IMPORTANT]
> 🇵🇸 **URGENT GAZA HUMANITARIAN EMERGENCY**
> This project is free for personal wealth management and source-available. If you find value in this software, please consider supporting vital civilian relief efforts directly through trusted global organizations:
> - **[UNRWA Gaza Emergency](https://www.unrwa.org/gaza-emergency)** — Direct support for food, shelter, and medical care.
> - **[Islamic Relief Palestine Appeal](https://www.islamicreliefcanada.org/emergencies/palestine-appeal)** — Critical humanitarian aid and medical supplies.
>
> *Humanitarian Notice: This project is independent and has no political, governmental, or military affiliations. These links are provided solely for humanitarian purposes.*
## 🌟 Capabilities & Features
CairnIQ is designed as a private command center for your personal finances, merging live broker data with deep AI reasoning.
### 1. Multi-Agent Artificial Intelligence
- **Deep Reasoning Engine:** Automatically breaks down complex financial queries into multi-step execution plans.
- **Market Pulse Analyst:** Interprets broad macroeconomic trends (Fear & Greed, VIX, S&P 500 regimes) to gauge overall market safety.
- **Opportunity Scanner:** Continuously scans the market for high-conviction structural shifts and cyclical opportunities.
- **Policy Signal Tracking ("Trump Yap"):** Pulls Donald Trump's latest Truth Social posts in real time to weigh potential market and supply-chain impact.
### 2. Financial Connectivity Hub
Manage your data feeds securely from a unified dashboard.
- **Alpaca Markets (US & Global):** Full integration for real-time market data and paper-trading capabilities.
- **Questrade (Canada):** Securely track your TFSA, RRSP, and Margin accounts in real-time.
- **Zero-Trust CSV Tracking:** Privacy-conscious? Keep your keys to yourself. Download our CSV template, fill in your holdings, and upload it directly via the UI.
### 3. Automated Valuation & Technicals
- **Fundamental Analysis:** The AI automatically pulls and synthesizes P/E, P/S, EV/EBITDA, and FCF Yields from external APIs (FMP, AlphaVantage).
- **Technical Indicators:** Real-time generation of moving averages, RSI, and MACD momentum signals.
---
## 🚀 Onboarding & Quick Start
### 1. Installation
Ensure you have Python 3.11, 3.12, or 3.13 installed on your machine. Python 3.14+ is not yet supported (transitive Pydantic V1 compat shim is incompatible).
```bash
# Clone the repository
git clone https://github.com/aymanyaq/cairniq.git
cd cairniq
```
**macOS / Linux** — run the automated installer:
```bash
./install.sh
```
**Windows** — open PowerShell in the project folder and run:
```powershell
powershell -ExecutionPolicy Bypass -File install.ps1
```
> [!TIP]
> **Guided Setup**: The installer will offer to launch an interactive **Setup Wizard** at the end. This wizard helps you configure your AI provider (Bedrock, Anthropic, OpenAI, or Azure OpenAI / AI Foundry), link your brokerage, and set up your personal financial profile without manually editing any files.
> [!TIP]
> **Safe Installation**: The installer automatically detects existing user data and creates a timestamped backup in the `backups/` directory before any changes are made. It will also migrate legacy data files into the protected `user_data/` zone automatically.
### 2. Launching CairnIQ
Once installed, double-click the desktop launcher the installer created, or run from the project folder:
| Platform | Command |
|----------|---------|
| macOS / Linux | `./CairnIQ.command` |
| Windows | `CairnIQ.bat` |
The application will automatically open in your web browser at `http://localhost:8000`.
### 3. Data Management & Backups
Your persistent state is stored in `user_data/`. The system includes utilities for maintenance:
- **Backup Location**: `backups/user_data_YYYYMMDD_HHMMSS.tar.gz`
- **Restore Data**: `./scripts/install/restore_backup.sh`
- **Verify Integrity**: `python3 scripts/install/verify_data.py`
- **Tune the opportunity scanner**: edit `user_data/funnel_config.json` (auto-created from `funnel_config.example.json` on install/first run). See the [Funnel Configuration Guide](docs/technical/FUNNEL_CONFIG.md).
### 4. "Bring Your Own Key" (BYOK) Setup
We believe your data and API usage should remain under your control. When you first launch the application:
1. Navigate to the **Settings** page in the left sidebar.
2. Enter your preferred **LLM Provider Keys** (AWS Bedrock, Anthropic, OpenAI, Azure, or Google) - **one is required**.
3. Enter your **Financial Data Keys** (recommended but optional with fallbacks):
- **FMP (Recommended)** - Provides insider trades, senate data, and earnings transcripts (no fallback available)
- **Alpha Vantage (Optional)** - Quotes and fundamentals (falls back to yfinance)
- **FRED, Finnhub, Polygon, Tavily (Optional)** - Enhance capabilities but have fallbacks
4. Connect your **Brokerage** (Alpaca or Questrade) in the Financial Connectivity Hub - **optional, CSV alternative available**.
5. Click **Commit Infrastructure Sync**.
Your keys are saved *locally* and are never transmitted to any central server. On desktop platforms, CairnIQ stores secrets in the OS keychain when available and keeps only blank placeholders in `user_data/.env`.
---
## 💼 Managing Your Portfolio
The console aggregates your holdings into a single pane of glass. You have two ways to feed data into the engine:
**Method A: Live Broker Sync**
Enter your brokerage API credentials in the Settings menu. CairnIQ will automatically poll and synchronize your holdings.
**Method B: Manual Entry (Zero-Trust)**
1. Navigate to the **Portfolio** tab.
2. Click **Download CSV Template**.
3. Fill out your positions (Symbol, Shares, Entry Price) in Excel or Numbers.
4. Click **Upload CSV** to instantly populate your dashboard.
CairnIQ handles deduplication automatically—live syncs take precedence over manual CSV entries for the same account.
---
## 📜 License & Usage Policy
**Personal Wealth Management Non-Commercial License**
This software is licensed **strictly for personal, non-commercial use.**
- ✅ **Allowed:** Managing your personal portfolio, learning about the markets, personal financial research.
- ❌ **Prohibited:** Use within a hedge fund, family office, proprietary trading firm, or any corporate entity. You may not monetize this software or use it to manage third-party assets for a fee.
Please see the [LICENSE](LICENSE) file for the full legal text.
### API Data Compliance
This project does not redistribute or re-sell raw financial data. You are responsible for ensuring that your usage of third-party API keys (Alpha Vantage, FMP, etc.) complies with their respective Terms of Service.
---
## 📚 Documentation
Browse the full documentation in [`docs/`](docs/README.md). Highlights:
**For users:**
- 📦 [Installation & Provider Setup Guide](docs/user-guide/INSTALLATION.md) — installer walkthrough, Guided Setup Wizard, LLM/data provider comparison, fallback architecture
- 📖 [User Guide](docs/user-guide/USER_GUIDE.md) — chat interface, agent routing, portfolio management, memory system, thesis journal
- 🛠️ [Troubleshooting](docs/user-guide/TROUBLESHOOTING.md) — common install, startup, API, performance, and data issues
- 🚀 [Launcher Modes](docs/LAUNCHER_MODES.md) — production (`CairnIQ.command`) vs demo (`start_demo.sh`)
**For developers:**
- 🧭 [Project Structure](docs/PROJECT_STRUCTURE.md) — directory layout, core components, data flow
- 🏛️ [Architecture](docs/technical/ARCHITECTURE.md) — runtime shape, agent flow, operational constraints
- 🌐 [API Reference](docs/technical/API.md) — every REST/SSE endpoint with request/response shapes
- 🧪 [Adding Tools](docs/technical/ADDING_TOOLS.md) — extending the agent's capabilities
- 🔌 [Tool Capabilities](docs/technical/TOOL_CAPABILITIES.md) — inventory of available tools and their inputs
---
## 📋 Changelog
See the [CHANGELOG](docs/CHANGELOG.md) for a detailed history of changes.