TrustVault: Autonomous Multi-Agent Financial Risk Governance & Portfolio Engine

Autonomous multi-agent system executing real-time financial market perception, multi-perspective risk vetoes, dynamic capital allocation, double-entry verification, and immutable hash-chained audit trails.

Service	Environment	Status	Configuration
Autonomous Decision Loop	Python Asyncio Daemon		1.5σ delta / 30s evaluation tick
Multi-Agent Consensus API	FastAPI / Uvicorn		http://localhost:8000
Executive Trading Terminal	React 19 / Vite		http://localhost:5173
Immutable Audit Ledger	PostgreSQL 16 (asyncpg)		Port 5432 (Docker)
Telemetry & Stream Bus	Redis 7		Port 6379 (Docker)

---

Executive Summary

TrustVault is an autonomous financial risk governance and execution engine that unifies real-time market data ingestion with multi-agent consensus validation. Rather than relying on fragile single-model price prediction heuristics, TrustVault models trading decisions as a formal risk-constrained consensus problem.

Before any capital is committed, a quorum of six specialized agents evaluates expected return, market liquidity, execution slippage, conditional volatility, portfolio exposure, and risk mandate compliance. Every transaction is size-constrained via fractional Kelly criteria, recorded in a double-entry accounting ledger, and written to an immutable SHA-256 hash-chained audit log for regulatory compliance.

---

System Architecture

TrustVault operates as a continuous, closed-loop decision pipeline with independent veto capabilities at every stage:

flowchart TD
    subgraph PERCEPTION["1. Market Perception & Ingestion"]
        FEED["Order Book Feed<br/>Price, Spread, Depth, Imbalance"] --> OBS["Observation State<br/>(Carries Millisecond Age)"]
        NEWS["Financial News Stream<br/>Scored Sentiment Vectors"] --> OBS
        OBS --> STALE{"Staleness Check<br/>Age <= Max Latency?"}
        STALE -->|"No"| DENY_STALE["Decline Execution<br/>Stale Telemetry Veto"]
    end

    subgraph RISK_ALLOCATION["2. Dynamic Risk & Sizing"]
        STALE -->|"Yes"| ALLOC["Capital Allocator<br/>Fractional Kelly + Volatility Target"]
        ALLOC --> CLIP{"Capital Bound<br/>Size > Zero?"}
        CLIP -->|"No"| DENY_CAP["Decline Execution<br/>Mandate Constraint Bound"]
    end

    subgraph CONSENSUS["3. Six-Expert Agent Quorum"]
        direction TB
        CLIP -->|"Yes"| E1["Signal Expert<br/>Directional Edge"]
        CLIP -->|"Yes"| E2["Sentiment Expert<br/>Macro Narrative"]
        CLIP -->|"Yes"| E3["Volatility Expert<br/>Downside Survivability"]
        CLIP -->|"Yes"| E4["Exposure Expert<br/>Concentration & Mandate"]
        CLIP -->|"Yes"| E5["Liquidity Expert<br/>Spread & Depth Costs"]
        CLIP -->|"Yes"| E6["Correlation Expert<br/>Cross-Asset Beta"]
        E1 & E2 & E3 & E4 & E5 & E6 --> SYNTH["Consensus Synthesis Engine"]
    end

    subgraph EXEC_AUDIT["4. Execution & Immutable Verification"]
        SYNTH -->|"Approve"| EXEC["Smart Order Router<br/>Crosses Book + Slippage Model"]
        SYNTH -->|"Review"| ESCALATE["Human-in-the-Loop Escalation"]
        SYNTH -->|"Deny"| AUDIT_DENY["Log Rejection Reason"]
        EXEC --> LEDGER["Double-Entry Ledger<br/>(Stitch / Local Database)"]
        LEDGER --> CHAIN["SHA-256 Hash-Chained Audit Trail"]
    end

    PERCEPTION --> RISK_ALLOCATION --> CONSENSUS --> EXEC_AUDIT

Loading

---

Problem Requirement Matrix

Requirement	Implementation Architecture	Target Component
Heterogeneous Feed Ingestion	Order book depth, bid-ask spread, and real-time sentiment scoring	market/feed.py, market/news.py
Multi-Dimensional Risk Veto	Six independent expert agents, each possessing unilateral veto authority	agents/market/experts.py
Dynamic Capital Constraints	Volatility targeting and fractional Kelly allocation	allocator.py, portfolio_service.py
Closed-Loop Adaptation	Realized outcome tracking updates agent voting weights over time	autonomous_loop.py, adaptation.py
Continuous Market Reassessment	Triggers on 1.5σ volatility moves, adverse news, or data staleness	autonomous_loop.py
Execution Cost Accounting	Crossing the book modeled against bid-ask spread and market impact	execution.py
Immutable Compliance Logging	Cryptographically chained audit logs with verifiable SHA-256 hashes	consensus.py, PostgreSQL

---

Quantitative & Mathematical Methodology

1. Capital Allocation & Sizing (Fractional Kelly)

Position sizing $f^*$ is derived from expected excess return $\mu$, conditional variance $\sigma^2$, and risk aversion parameter $\gamma$:

$$f^* = \min \left( \frac{\mu}{\gamma \sigma^2}, ; f_{\max} \right)$$

When conditional volatility spikes above historical thresholds, the capital allocator automatically clips $f^*$ to preserve portfolio drawdown limits.

2. Weighted Quorum Consensus

Each of the six expert agents outputs a decision $d_i \in {-1, 0, 1}$ (Sell, Neutral, Buy) accompanied by a confidence score $c_i \in [0, 1]$. The aggregated consensus score $S_{\text{consensus}}$ is computed as:

$$S_{\text{consensus}} = \frac{\sum_{i=1}^{6} w_i \cdot c_i \cdot d_i}{\sum_{i=1}^{6} w_i}$$

• Abstention on Failure: If an agent encounters network timeouts or LLM failure, it defaults to $c_i = 0$ (Abstain), preventing silent consent.
• Mandate Invariance: The Exposure Agent's veto weight $w_{\text{exposure}}$ is invariant to P&L, preventing the system from overriding capital preservation rules.

3. Cryptographic Hash-Chained Audit Trail

Every system action, telemetry snapshot, expert vote, and order fill generates an immutable audit record $A_t$:

$$H_t = \text{SHA256}(H_{t-1} \parallel t \parallel \text{DecisionID} \parallel \text{VotePayload} \parallel \text{ExecutionFill})$$

The ledger provides mathematical proof against tampering, revisionism, or retroactive trade insertions.

---

Core Integrations

• Stitch Ledger: Programmable double-entry bookkeeping adapter. Each asset reallocation records balanced debits and credits. When external API keys are omitted, the local PostgreSQL ledger activates seamlessly without downtime.
• ElevenLabs Voice Telemetry: Real-time low-latency auditory telemetry. Translates complex multi-agent execution rationale into natural spoken briefings for operators and accepts spoken risk constraint overrides.

---

API Reference

Endpoint	Method	Description	Target Component
/api/market/snapshot	GET	Current order book snapshot with millisecond observation age	Market Perception
/api/market/decisions/{id}	GET	Full decision record including all 6 expert votes and SHA-256 hash	Audit Engine
/api/market/loop/cycle	POST	Triggers an immediate decision-making loop cycle	Orchestrator
/api/market/loop/pause	POST	Suspends active trading and loop execution	Operator Control
/api/market/loop/resume	POST	Resumes automated agent decision cycles	Operator Control
/api/portfolio	GET	Real-time Net Asset Value (NAV), gross exposure, and open drawdowns	Portfolio Service
/api/portfolio/ledger/trial-balance	GET	Validates that double-entry balance sheets maintain mathematical equality	Ledger Verification
/api/portfolio/agents/performance	GET	Historical precision, Sharpe ratios, and active voting weights per agent	Adaptation Layer
/api/telemetry/infrastructure	GET	Real-time Redis, PostgreSQL, and LLM inference latencies	Telemetry Deck
/api/voice/briefing	GET	Synthesizes an executive natural-language market briefing	ElevenLabs Voice

---

Technology Stack

Layer	Technologies
Backend & Orchestrator	Python 3.11+, FastAPI, Uvicorn, Asyncio, Pydantic v2
Multi-Agent Reasoning	Ollama, NVIDIA NIM, OpenAI API, LangChain / Structured Output
Frontend Terminal	React 19, TypeScript, Vite, Tailwind CSS, Lucide Icons
Database & Cache	PostgreSQL 16 (AsyncPG, SQLAlchemy), Redis 7
Voice & Speech	ElevenLabs Real-Time Voice API
Containerization	Docker, Docker Compose

---

Quick Start & Local Execution

1. Launch Infrastructure Services

# Clone the repository
git clone https://github.com/Manimaran-tech/trust-vault.git
cd trust-vault

# Start PostgreSQL and Redis containers
docker-compose up -d

2. Configure Environment Variables

Copy .env.example to .env and verify configurations:

# LLM Provider Configuration
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=qwen3:8b
LLM_API_KEY=ollama

# Database Connections
DATABASE_URL=postgresql+asyncpg://trustvault:trustvault@localhost:5432/trustvault
REDIS_URL=redis://localhost:6379/0

3. Launch Backend Server

cd backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. Launch Frontend Terminal

cd ../frontend
npm install
npm run dev

Open http://localhost:5173 to access the live trading dashboard. Interactive API documentation is available at http://localhost:8000/docs.

---

License

This project is licensed under the MIT License — see the LICENSE file for details.