TidalShift

A cross-domain cascading pathway analysis engine powered by AI agent swarms. TidalShift maps plausible causal chains across financial markets, economic behavior, and policy dynamics using structured multi-agent debate.

Not a prediction engine — it's a scenario exploration and causal chain mapping tool. Submit a scenario like "What if the Fed cuts rates by 50bp?" and receive ranked cascading pathways with full debate records, confidence scores, and key points of uncertainty.

How It Works

TidalShift uses a three-tier agent hierarchy orchestrated via LangGraph:

• Tier 1 — Pathway Orchestrator: Receives scenarios, orchestrates cross-domain analysis, adjudicates disputes, produces final pathway maps
• Tier 2 — Domain Specialists: 15 specialists (5 market + 5 economic + 5 policy) plus 4 cross-domain bridge agents
• Tier 3 — Swarm Floors: 500–5,000 agents per domain across 8 archetypes, producing structured Domain Briefs via multi-round debate

Agents specialize in one domain but must defend their reasoning against agents from other domains — revealing causal chains, contradictions, and second-order effects that siloed analysis misses.

Architecture

ScenarioParser → GraphPrimer → ScenarioMemory → Decomposer → SwarmDispatcher
  → DomainParallelDispatch → {MarketCluster, EconomicCluster, PolicyCluster}
  → DomainSync → BridgeAgentRouter → CrossExamination → PathwayConstructor
  → PathwayOrchestrator → SensitivityAnalyzer → SurpriseDetector → OutputGenerator

Key Capabilities

• Parallel domain execution — 3 clusters run 5 specialists each concurrently
• Structured multi-agent debate — typed escalation challenges, cross-examination, dispute tracking
• Neo4j knowledge graph — blast radius pre-computation, causal chain traversal, historical analogs
• Multi-LLM diversity — 9 provider adapters (Anthropic, OpenAI, xAI, Google, DeepSeek, Mistral, Cohere, Meta, Ollama)
• Evolutionary learning — agent pruning/cloning, archetype rebalancing, cross-domain reputation tracking
• Continuous monitoring — real-time market/economic/policy/news feeds with auto-triggered analysis
• Budget enforcement — per-scenario cost tracking with graceful wrap-up
• Confidence decay — chain-length penalty, link-type calibration, provider diversity bonus

Tech Stack

Layer	Technology
Language	Python 3.12+
Backend	FastAPI + Uvicorn
Orchestration	LangGraph
LLM Providers	Anthropic, OpenAI, xAI, Google, DeepSeek, Mistral, Cohere, Meta, Ollama
Knowledge Graph	Neo4j (Community Edition)
Database	SQLite
Frontend	Vue.js 3 + Vite + TypeScript + Pinia + D3.js
Data Sources	yfinance, FRED, Alpha Vantage, Finnhub, LegiScan, Regulations.gov, NewsAPI, Serper

Getting Started

Prerequisites

• Python 3.12+
• Node.js 18+ (for frontend)
• Docker (for Neo4j)

Setup

# Clone the repository
git clone https://github.com/CTO92/TidalShift.git
cd TidalShift

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start Neo4j
docker-compose up -d neo4j

# Install Python dependencies
pip install -e ".[dev]"

# Run the backend
cd tidalshift && uvicorn main:app --reload

# Run the frontend (separate terminal)
cd frontend && npm install && npm run dev

Configuration

• LLM assignments: llm_config.json — per-agent provider and model selection
• Learning weights: learning_config.json — evolutionary learning parameters
• Environment variables: .env — API keys and application settings
• Intensity profiles: minimal, balanced, thorough, maximum

API

The backend exposes a REST API at http://localhost:8000/api/:

Endpoint	Description
POST /api/scenarios	Submit a scenario for analysis
GET /api/pathways/{id}	Retrieve pathway results with debate records
GET /api/graph/explore	Explore the knowledge graph
GET /api/alerts	View monitoring alerts
WS /ws/analysis/{id}	Stream live analysis progress
POST /api/comparisons	Compare scenarios side-by-side
GET /api/performance/*	Agent/provider performance metrics

Project Structure

tidalshift/
├── main.py                  # FastAPI entry point
├── config.py                # Configuration & env vars
├── api/                     # REST API routes (10 routers)
├── orchestration/           # LangGraph pipeline & agents
│   ├── agents/              # Tier 2 domain specialists
│   ├── debate/              # Multi-tiered debate engine
│   └── output/              # Pathway construction & rendering
├── swarm/                   # Tier 3 swarm floors
├── channels/                # Cross-domain signal channels
├── ingestion/               # Continuous data monitoring
├── consensus/               # Confidence & pathway ranking
├── learning/                # Evolutionary feedback loops
├── llm/                     # Multi-LLM provider system
├── graph/                   # Neo4j knowledge graph
├── tools/                   # Agent tools
├── db/                      # SQLite persistence
└── tests/
frontend/                    # Vue.js 3 SPA
├── src/
│   ├── views/               # 8 page views
│   ├── components/          # 41 components
│   ├── stores/              # Pinia state management
│   └── api/                 # API client layer

License

This project is licensed under the Apache License 2.0 — see the Apache License 2.0 for details.