Quant Nanggroe AI is a Multi-Agent Decision Intelligence Operating System for quantitative research and systematic trading in financial markets. It is part of the HermesQuantOS unified project ecosystem.
Built on the principle of Deterministic Decision Intelligence, the platform treats LLMs as Logical Reasoning Engines operating under strict contracts that forbid subjective opinions, mandate data grounding, and require pressure-based numerical outputs rather than direct trade signals.
The system implements a 5-Layer Execution Stack that processes market data from raw L1/L2 feeds through regime detection, multi-agent sensor analysis, pressure normalization, and decision synthesis with risk enforcement. It features a Darwinian Strategy Lifecycle that automatically retires underperforming strategies and a Risk Guardian Constitution as an independent layer of hard-coded safety rules.
Honest Note: This is a decision-support and research tool, not an autonomous trading system that guarantees profits. "Deterministic Decision Intelligence" means the data flow pipeline is deterministic β not that its outputs are guaranteed correct. All trading involves risk of loss. The Risk Guardian reduces but cannot eliminate risk.
The core of Quant Nanggroe AI is its layered execution architecture. Each layer has a single responsibility and strict data contracts with the layers above and below it. This is what makes the pipeline deterministic β the same inputs always follow the same processing path, producing auditable, traceable decision artifacts.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LAYER 4 β DECISION β
β Decision Synthesis & Risk Enforcement β
β Final pressure vector β action recommendation β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β LAYER 3 β NORMALIZATION β
β Pressure Normalization & Conflict Resolution β
β Multi-agent outputs β unified pressure vector β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β LAYER 2 β SENSORS β
β Multi-Agent Sensor Analysis & Interpretation β
β Regime context β specialized agent analysis β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β LAYER 1 β REGIME β
β Market Regime Detection & Classification β
β Raw market data β regime labels & transitions β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β LAYER 0 β DATA β
β Data Foundation & Market Feeds (L1/L2) β
β External feeds β normalized internal data model β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
The bedrock layer ingests raw market data from multiple providers and normalizes it into a unified internal data model.
- L1/L2 Feed Ingestion β Real-time order book snapshots, trade prints, and ticker updates from Binance and fallback providers
- AutoSwitch Data Engine β Automatic failover between data providers (Binance β CoinCap β AlphaVantage β Polygon β Finnhub) with latency tracking
- Normalization Pipeline β All incoming data is mapped to a canonical schema regardless of source, ensuring upstream layers never need provider-specific logic
- Historical Replay β Cached tick data enables deterministic replay for backtesting and audit trails
Processes normalized data to identify the current market regime, which governs how all downstream agents interpret signals.
- Regime Classification β Labels market state (trending, mean-reverting, volatile, quiet, transitional) using statistical and structural indicators
- Transition Detection β Identifies regime shifts in real-time, triggering agent reconfiguration
- Context Propagation β Broadcasts regime labels to all Layer 2 sensors, ensuring every agent operates within the correct market context
- Confidence Scoring β Each regime label carries a confidence score; low-confidence regimes trigger conservative agent behavior
Specialized agents analyze the market within the context provided by Layer 1. Each agent is a narrow expert, not a generalist.
- Technical Sensor β Pattern recognition, momentum, mean-reversion, and volatility analysis
- Sentiment Sensor β NLP-based sentiment extraction from news, social, and on-chain data
- Macro Sensor β Interest rates, funding rates, correlation shifts, and cross-asset analysis
- Liquidity Sensor β Order book depth analysis, slippage estimation, and flow detection
- Volatility Sensor β Realized vs. implied volatility, regime-adjusted volatility forecasting
- On-Chain Sensor β Whale movements, exchange flows, and smart money tracking (crypto markets)
Each sensor produces a pressure vector (directional bias + magnitude) rather than a binary signal, enabling nuanced downstream synthesis.
Receives pressure vectors from all active sensors and resolves conflicts into a unified assessment.
- Weighted Aggregation β Sensor pressures are weighted by historical accuracy in the current regime
- Conflict Resolution β When sensors disagree, the system reduces overall confidence rather than picking a winner
- Temporal Smoothing β Prevents whipsaw by requiring sustained pressure before adjusting the aggregate
- Darwinian Weighting β Sensors with consistently poor performance in a given regime have their weights automatically reduced (linked to the Strategy Lifecycle)
The final layer combines the normalized pressure vector with portfolio state and risk constraints to produce an action recommendation.
- Position Sizing β Kelly-derived sizing modulated by current portfolio heat and regime confidence
- Risk Guardian Gate β Every recommendation passes through the Risk Guardian Constitution before reaching the execution layer. The Guardian can block, reduce, or modify any action
- Audit Trail β Every decision is logged with full provenance: which sensors contributed, their weights, regime context, and Guardian rulings
- Action Output β The system outputs a structured decision artifact (not a direct trade order), which a human operator or downstream execution system can act upon
- 5-Layer Execution Stack β Deterministic data flow from raw feeds to decision artifacts, with strict layer contracts and full audit trails
- Deterministic Pipeline β Every decision is traceable, auditable, and defensible. The same inputs follow the same processing path every time
- Darwinian Strategy Lifecycle β Strategies and sensors are continuously evaluated; underperformers are automatically retired and replaced with evolved variants
- Risk Guardian Constitution β Independent hard-coded safety rules immune to AI reasoning that can block, reduce, or modify any action regardless of agent confidence
- Desktop-OS UI β Dashboard interface with real-time visualization of agent states and pressure vectors
- AutoSwitch Data Engine β Automatic failover between data providers (Binance, CoinCap, AlphaVantage, Polygon, Finnhub) with latency-aware routing
- Pressure-Based Outputs β Agents produce continuous pressure vectors (direction + magnitude), not binary signals, enabling nuanced decision-making
- Regime-Aware Analysis β All agents operate within detected market regime context, reducing false signals from regime-inappropriate strategies
- Full Provenance Audit β Every decision artifact includes which sensors contributed, their weights, regime context, and Guardian rulings
ββββββββββββββββββββββββ
β Dashboard UI β
β (FastAPI + REST) β
β ββββββββββββββββ β
β β CLI (qnai) β β
β β REST API β β
β β WebSocket β β
β ββββββββ¬ββββββββ β
βββββββββββΌβββββββββββββ
β
βββββββββββΌβββββββββββββ
β Layer 4: Decision β
β βββββββββββββββββββ β
β β Risk Guardian βββββββ Constitution
β β Position Sizer β β (Hard Rules)
β β Audit Logger β β
β ββββββββββ¬βββββββββ β
βββββββββββββΌββββββββββββ
β
βββββββββββββΌββββββββββββ
β Layer 3: Normalizer β
β βββββββββββββββββββ β
β β Weighted Agg β β
β β Conflict Res β β
β β Darwinian Wt ββββββ Strategy
β ββββββββββ¬βββββββββ β Lifecycle
βββββββββββββΌββββββββββββ
β
ββββββββββββ¬ββββββββΌββββββββ¬βββββββββββ
β β β β
βββββββΌββββ βββββΌββββββ βββββββββΌβββ ββββββΌβββββ
βTechnicalβ βSentimentβ βLiquidity β βOn-Chain β
β Sensor β β Sensor β β Sensor β β Sensor β
βββββββ¬ββββ βββββ¬ββββββ βββββββββ¬βββ ββββββ¬βββββ
β β β β
βββββββΌββββββββββΌββββββββββββββββΌββββββββββΌβββββ
β Layer 1: Regime Detection β
β ββββββββββββββββββββββββββββββββββββββββ β
β β Classifier β Transitions β Confidence β β
β ββββββββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββ¬ββββββββββββββββββββββββ
β
ββββββββββββββββββββββββΌββββββββββββββββββββββββ
β Layer 0: Data Foundation β
β βββββββββ βββββββββββ βββββββββ βββββββββ β
β βBinanceβ βCoinCap β βPolygn β βFinnhb β β
β βββββββββ βββββββββββ βββββββββ βββββββββ β
β AutoSwitch Data Engine β
βββββββββββββββββββββββββββββββββββββββββββββββ
We believe in radical transparency. Here are the limitations and clarifications you should know before using this project.
| Claim | Reality |
|---|---|
| "Deterministic Decision Intelligence" | The data flow pipeline is deterministic β same inputs follow the same path. This does not mean outputs are guaranteed correct. |
| "Decision Intelligence OS" | This is a decision-support tool. It produces structured decision artifacts for human review, not autonomous trade execution. |
| "Risk Guardian" | Reduces risk through hard-coded safety rules, but cannot eliminate risk. Market conditions can exceed any risk model. |
| "Darwinian Strategy Lifecycle" | Automatically retires poor strategies based on metrics, but past performance does not guarantee future results. |
| "Multi-Agent Analysis" | Multiple agents provide diverse perspectives, but diverse analysis does not equal correct analysis. |
| Part of HermesQuantOS | This project is one component of the larger HermesQuantOS ecosystem. |
Critical reminders:
- All trading involves significant risk of loss
- This software is for education and research purposes
- Always test with paper trading before committing real capital
- Never risk more than you can afford to lose
- Past backtest results do not predict future performance
- Python >= 3.11
- pip >= 23.x (or uv/poetry)
- Binance API key (use testnet first)
# Clone the repository
<!-- AUTO-PACKAGE-BADGES:START -->
<!-- Auto-generated package badges -->
   [](https://www.npmjs.com/package/crucix)
   [](https://pypi.org/project/quant-nanggroe-ai)
<!-- AUTO-PACKAGE-BADGES:END -->
git clone https://github.com/mulkymalikuldhrs/Quant-Nanggroe-AI.git
cd Quant-Nanggroe-AI
# Install dependencies
pip install -r requirements.txt
# Or install the quant-nanggroe-ai package
pip install -e .
# Configure environment
cp .env.example .env
# Edit .env with your API keys (use testnet keys for initial testing)
# Run the CLI
qnai run --symbols BTC/USDT --provider openai
# Or start the API server
qnai serve --port 8000# Required β Data Provider
QNAI_BINANCE_API_KEY=your_testnet_key
QNAI_BINANCE_API_SECRET=your_testnet_secret
# Optional β Fallback Data Providers
QNAI_ALPHA_VANTAGE_API_KEY=
QNAI_POLYGON_API_KEY=
QNAI_FINNHUB_API_KEY=
# Optional β LLM Reasoning Engine
QNAI_OPENAI_API_KEY=
# IMPORTANT: Risk limits are CONSTITUTIONAL and CANNOT be overridden via env vars.
# They are defined in quant_nanggroe/engine/risk/constants.py
# Do NOT set QNAI_RISK_MAX_PER_TRADE or similar β they will be rejected at startup.Important: Always start with Binance Testnet. Never connect to mainnet with untested configurations.
from quant_nanggroe.exchange.ccxt_broker import CCXTBroker
from quant_nanggroe.exchange.paper_broker import PaperExchangeBroker
# Paper trading (default, safe)
broker = PaperExchangeBroker()
await broker.connect()
# Real exchange via CCXT
broker = CCXTBroker(exchange_id="binance", api_key=key, api_secret=secret)
await broker.connect()
# Get ticker data
ticker = await broker.get_ticker("BTC/USDT")
print(ticker.last_price, ticker.bid, ticker.ask)from quant_nanggroe.engine.risk.manager import RiskManager
rm = RiskManager()
status = rm.status()
# status includes: daily_pnl, weekly_pnl, drawdown, kill_switch statefrom quant_nanggroe.agents import TradingGraph
# Build the multi-agent trading graph
graph = TradingGraph(
llm_provider="openai",
deep_think_model="gpt-4o",
quick_think_model="gpt-4o-mini",
api_key="your-openai-key",
)
# Run the pipeline
result = graph.run(
symbols=["BTC/USDT", "ETH/USDT"],
trade_date="2025-01-15",
)
# result includes: risk_verdict, decisions, signals, agent_outputsfrom quant_nanggroe.engine.risk.checks import RiskCheckGate
from quant_nanggroe.engine.risk.constants import (
MAX_RISK_PER_TRADE, MAX_DAILY_LOSS, MAX_WEEKLY_LOSS,
)
# All constants are Final and cannot be overridden
print(f"Max risk per trade: {MAX_RISK_PER_TRADE:.2%}") # 0.50%
print(f"Max daily loss: {MAX_DAILY_LOSS:.2%}") # 1.00%
print(f"Max weekly loss: {MAX_WEEKLY_LOSS:.2%}") # 3.00%
# Run the 9-checkpoint risk gate
gate = RiskCheckGate()
result = gate.evaluate(symbol="BTC/USDT", direction="BUY",
position_size_pct=0.05, portfolio_value=100000)from quant_nanggroe.engine.risk.kill_switch import KillSwitch
# Kill switch with file-based persistence
ks = KillSwitch()
# Check if kill switch is active (persists across restarts)
if ks.is_active:
print("TRADING HALTED - manual reset required")
# Auto-trigger based on risk limits
ks.check_auto_trigger(
daily_loss_pct=0.009,
weekly_loss_pct=0.02,
drawdown_pct=0.12,
)from quant_nanggroe.engine.risk.constants import (
MAX_RISK_PER_TRADE, # 0.5% per trade (Final, immutable)
MAX_DAILY_LOSS, # 1% daily loss (Final, immutable)
MAX_WEEKLY_LOSS, # 3% weekly loss (Final, immutable)
MAX_DRAWDOWN_PCT, # 15% max drawdown (Final, immutable)
KILL_SWITCH_DAILY_PNL, # -0.8% early warning before 1% hard limit
)
# These limits are constitutional β they CANNOT be overridden
# by environment variables, agents, or configuration.
# Any attempt to set QNAI_RISK_MAX_PER_TRADE etc. will cause
# a RuntimeError at startup.Contributions are welcome! We especially value contributions that improve transparency, risk management, and honest documentation.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Do not add features that overclaim about trading performance or guaranteed returns
- Do improve risk management, error handling, and audit trail capabilities
- Do add tests for any new logic in the execution stack
- Do update documentation to reflect any behavioral changes
- Code style follows the existing Python strict configuration
# Install dependencies
pip install -e ".[dev]"
# Run the CLI
qnai run --symbols BTC/USDT
# Run type checking
mypy quant_nanggroe/
# Run linting
ruff check quant_nanggroe/
# Run tests
pytest
# Start API server
qnai serveFOR EDUCATION AND RESEARCH PURPOSE ONLY
This project is provided strictly for educational and research purposes. The authors and contributors assume no responsibility or liability for any financial damages, losses, or risks arising from the use of this software.
Key risks:
- All trading involves significant risk of loss. You can lose your entire investment and more.
- Past performance does not guarantee future results. Backtested strategies may fail in live markets.
- The Risk Guardian reduces but cannot eliminate risk. Market conditions can exceed any risk model's assumptions.
- Decision-support outputs are not financial advice. The system produces structured decision artifacts β you are solely responsible for any trading decisions you make.
- We do not bear any responsibility or risk for how this software is used.
- Always use testnet/paper trading before connecting to live markets with real capital.
This repository contains the ai_multicolony framework β a colony-based autonomous agent operating system that provides the infrastructure layer for the broader AI-MultiColony-Ecosystem. It is distinct from the Quant-Nanggroe-AI trading layer and serves as the general-purpose multi-agent orchestration platform.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β API Layer (FastAPI + WebSocket) β
β REST routes, schemas, auth, rate limiting β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Colony Layer β
β Colony Manager β’ Hands β’ A2A Communication β’ Scheduling β
ββββββββββββββ¬βββββββββββββ¬βββββββββββββ¬ββββββββββββββββββββββββ€
β Agents β Tools β Memory β MCP β
β Registry β Registry β Manager β Server/Client β
β Lifecycle β Shell/Codeβ Paging β JSON-RPC β
β Planner β Browser β Vector β Permissions β
β Executor β Search β Knowledge β Rate Limiting β
β Coder β Docker β Condensersβ Transport (stdio/sse)β
ββββββββββββββ΄βββββββββββββ΄βββββββββββββ΄ββββββββββββββββββββββββ€
β Infrastructure β
β Config β’ Logging β’ Security β’ Audit β’ Exceptions β’ Worker β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Module | Path | Description |
|---|---|---|
| agents | ai_multicolony/agents/ |
Agent types (Manus, Planner, Executor, Coder, Browser, Voice, Security, Researcher, Colony), registry, shared state |
| colony | ai_multicolony/colony/ |
Colony management, Hands system (Security, Code, Research, Browser, Voice, Compute, Integration), A2A coordinator, task scheduler |
| api | ai_multicolony/api/ |
FastAPI application with REST routes (agents, colonies, tasks, tools, memory, ecosystem, WebSocket), middleware (auth, rate limit, logging, error handling) |
| tools | ai_multicolony/tools/ |
Built-in tool implementations: Shell, File, Browser, Search, Code, MCP, Docker, Voice, Memory, Channel |
| memory | ai_multicolony/memory/ |
Multi-tier memory with paging, vector store, knowledge base, and 8 condenser types (summary, extraction, temporal, rollup, dedup, priority, sliding window, hierarchical) |
| mcp | ai_multicolony/mcp/ |
Model Context Protocol server and client with JSON-RPC, SSE/stdio transport, permissions engine, rate limiting |
| types | ai_multicolony/types/ |
All Pydantic v2 models: agent, colony, task, tool, memory, security, A2A, channel, event types |
| security | ai_multicolony/security/ |
Security analyzer, audit trail, permission engine |
| channels | ai_multicolony/channels/ |
Telegram, WhatsApp, Discord, Slack integrations |
| browser | ai_multicolony/browser/ |
Browser automation with stealth patterns and human behavior simulation |
| harness | ai_multicolony/harness/ |
Agent orchestration graph, skill registry, sandbox manager, harness memory |
| organism | ai_multicolony/organism/ |
Self-evolution: sense engine, decision engine, solution factory, immune system, growth engine |
| finance | ai_multicolony/finance/ |
Financial intelligence: risk guard, kill switch, market regime detector, pressure engine, autoswitcher |
| sources | ai_multicolony/sources/ |
Intelligence sources: OSINT, economic, market data with source manager |
| integrations | ai_multicolony/integrations/ |
External framework adapters: CrewAI, AutoGen, LangGraph |
| config | ai_multicolony/config/ |
Pydantic-settings based configuration with env var support (MULTICOLONY_* prefix) |
| sandbox | ai_multicolony/sandbox/ |
Docker and WASM sandbox implementations |
βββββββββββββββββββββββββββββββββββββββββββ
β AI-MultiColony-Ecosystem β
β ββββββββββββββββ ββββββββββββββββββββ β
β β ai_multicolonyβ β quant_nanggroe β β
β β (framework) β β (trading layer) β β
β β β β β β
β β Colony mgmt β β 5-Layer Stack β β
β β Agent infra β β Risk Guardian β β
β β MCP/Tools β β Data Engine β β
β β Memory β β Strategy Engine β β
β ββββββββ¬ββββββββ ββββββββββ¬ββββββββββ β
β ββββββββββββ¬βββββββββ β
β β β
β ββββββββββββΌβββββββββββ β
β β Shared Infrastructure β
β β API, DB, Redis, Worker β
β βββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββ
The ai_multicolony framework provides the general-purpose multi-agent infrastructure (colony management, tool execution, memory, MCP, security). The quant_nanggroe package layers trading-specific logic (5-layer execution stack, risk guardian, data engine) on top. Both share the same API server, database, and worker infrastructure.
| Component | Status | Notes |
|---|---|---|
| Type definitions | β Real | Comprehensive Pydantic v2 models with validators |
| Agent base classes | β Real | BaseAgent with lifecycle, event bus, circuit breaker |
| Colony management | β Real | Colony, Hands, A2A coordinator, scheduler |
| MCP server/client | β Real | JSON-RPC, SSE transport, permissions |
| Memory system | Models and managers defined; vector store needs ChromaDB backend | |
| Tools | Shell/File tools work; Browser/Search need external services | |
| Channels | Structured but need actual bot tokens and API keys | |
| API routes | β Real | FastAPI routes with proper schemas |
| Security | Audit trail works; permission engine is scaffolded | |
| Organism/Self-evolution | π Planned | Sense/Decision/Factory/Immune/Growth are architectural stubs |
| Finance layer | π Planned | Models exist but need real market data connections |
| Dashboard | Next.js UI with hardcoded mock data β see USE_MOCK_DATA flags |
|
| Integrations | π Planned | Adapter stubs for CrewAI, AutoGen, LangGraph |
| Sandbox | π Planned | Docker/WASM sandbox scaffolding exists |
Legend: β
Real and functional |
# Install the framework
pip install -e .
# Configure environment
export MULTICOLONY_API_JWT_SECRET="your-secret-key-here"
export MULTICOLONY_DEBUG=true # Allows empty JWT secret for development
# Start the API server
amce serve --port 8000
# Or use the CLI
amce status
amce run --helpWe're building a family of open source tools! Check out our other projects:
| Project | Description | Stars |
|---|---|---|
| π Quant-Nanggroe-AI | AI-powered quantitative analysis for Nanggroe market | β |
| π§ AI-MultiColony-Ecosystem | Multi-agent AI colony simulation | β 3 |
| π Kalen | Smart scheduling & AI task management | β |
| π€ ProxyGateLLM | Multi-LLM gateway with priority fallback | β 36 |
| π§© Mnemosyne | Knowledge management & note-taking | β |
π Visit our Contributor Hub β 28 open source projects seeking contributors!
This project is licensed under the MIT License β see the LICENSE file for details.
MIT License
Copyright (c) 2024-2026 Mulky Malikul Dhaher
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Mulky Malikul Dhaher
Part of the HermesQuantOS Unified Project