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

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 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 — Direct support for food, shelter, and medical care.
• Islamic Relief 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).

# Clone the repository
git clone https://github.com/aymanyaq/cairniq.git
cd cairniq

macOS / Linux — run the automated installer:

./install.sh

Windows — open PowerShell in the project folder and run:

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, OpenAI, or Anthropic), 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.

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, or OpenAI).
3. Enter your Financial Data Keys (AlphaVantage, FMP, FRED).
4. Connect your Brokerage (Alpaca or Questrade) in the Financial Connectivity Hub.
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 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/. Highlights:

For users:

• 📦 Installation & Provider Setup Guide — installer walkthrough, Guided Setup Wizard, LLM/data provider comparison, fallback architecture
• 📖 User Guide — chat interface, agent routing, portfolio management, memory system, thesis journal
• 🛠️ Troubleshooting — common install, startup, API, performance, and data issues
• 🚀 Launcher Modes — production (CairnIQ.command) vs demo (start_demo.sh)

For developers:

• 🧭 Project Structure — directory layout, core components, data flow
• 🏛️ Architecture — runtime shape, agent flow, operational constraints
• 🌐 API Reference — every REST/SSE endpoint with request/response shapes
• 🧪 Adding Tools — extending the agent's capabilities
• 🔌 Tool Capabilities — inventory of available tools and their inputs

---

📋 Changelog

See the CHANGELOG for a detailed history of changes.