# TORQ Console
**Enterprise Advisory Workbench powered by TORQ AI**
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/Version-v0.30.0-orange.svg)](https://github.com/pilotwaffle/TORQ-CONSOLE)
[![Status](https://img.shields.io/badge/Status-Production-green.svg)](https://github.com/pilotwaffle/TORQ-CONSOLE)

---

## Overview
TORQ Console is an enterprise advisory workbench that surfaces structured intelligence across advisory, market, document review, drafting, and orchestration workspaces. TORQ AI is the lead advisor, powered by a fine-tuned Qwen3-8B model (prince-flowers V4) and routed through a 4-tier model cascade. The system classifies every user message into a render type, routes it to the appropriate backend intelligence path, and returns structured payloads rendered on dedicated workspace canvases.

The frontend is a visualization and orchestration layer — not a chat app. Structured canvases own the center workspace. Chat is a demoted fallback renderer.

---

## Architecture

TORQ Console is a **governed, adaptive, agentic intelligence platform** — far more than a chat interface. It combines a clean React frontend with a layered, self-improving backend that enforces policy, learns from outcomes, and scales securely.

The entire system is visualized in [`workflows.html`](workflows.html) (open it in any browser). The single source of truth is [`workflows.json`](./workflows.json), which defines planes, nodes, flows, clusters, and interactive **view modes**.

### 4-Plane Architecture

The system is cleanly separated into four horizontal planes:

- **Operator Plane** — Human interface: chat, enforcement dashboard, memory inspector, observability dashboard, and Slack notifications.
- **Control Plane (Adaptive Intelligence)** — Prince Flowers core + governance, risk classification, routing, and policy evolution.
- **Execution Plane** — Runtime services: FastAPI backend, event bus, embedding pipeline, metrics, and external model providers.
- **Persistence Plane** — Supabase Postgres + pgvector RAG, decision memory, audit logs, and GitHub as source-of-truth.

### Prince Flowers — TORQ Intelligence Core

At the heart of the system sits **Prince Flowers**, the adaptive intelligence engine (highlighted in purple in the visualizer). It powers:

- **8-stage deterministic classifier**
- **L17–L28 Adaptive Intelligence Stack** — a numbered ladder of specialized layers:
  - L17 Evolution / Mutation Engine
  - L18 Governance Layer
  - L19 Predictive Intelligence
  - L20 Strategic Intervention
  - L21 Enforcement Ladder
  - L22.5 Context Pipeline
  - L22.6 Decision Memory
  - L25 Risk Classifier
  - L26 DefendSwarm Specialists
  - L27 4-Tier Model Router
  - L28 Experience Engine

This stack turns every decision into learning data, continuously evolving policy, prompts, and routing weights through a closed-loop feedback system.

### Key Flows & Capabilities

- **Live Proof Path** — The exact end-to-end production path (risk → enforcement → classification → routing → Claude response).
- **Risk-First Execution** — Every request is classified for risk (LOW/MED/HIGH/CRITICAL) before any model call.
- **Adaptive Learning Loop** — Decision events → Experience Engine (L28) → mutation proposals → governance approval → live policy updates.
- **Governance & Rollback** — Multi-party approval workflows, staged commits, append-only audit trail, and one-click rollback.
- **Observability Pipeline** — Full OpenTelemetry tracing + metrics surfaced in the operator dashboard.
- **RAG Ingestion & Retrieval** — Automatic freshness tracking from GitHub into pgvector.

### View Modes

The architecture visualizer supports multiple curated views so stakeholders see exactly what they need:

- **Working Now** — Live runtime only (green nodes)
- **Full System** — Everything, including planned and future items
- **Learning Loop** — Adaptive feedback cycle
- **Governance Loop** — Approval, audit, rollback
- **Failure Paths** — Rejection, block, retry, and degraded modes

### Design Principles

- **Risk-First + Enforcement** — Safety is never an afterthought.
- **Adaptive Intelligence** — The system literally improves itself from real outcomes (`torq_score`).
- **Tiered Intelligence** — Local Ollama → Zhipu GLM → Claude Sonnet/Opus with intelligent routing.
- **Governed Evolution** — No uncontrolled changes; every mutation goes through human + automated review.

Explore the full interactive diagram: [`workflows.html`](workflows.html)

---

## Features
### Export
- **PDF**: Print dialog via `window.open()` with styled HTML
- **DOCX**: Full markdown-to-Word conversion (headings, lists, blockquotes, tables, inline formatting) via `docx-js`
- **Markdown**: Direct `.md` file download

### Conversation Memory
- Messages stored in `chat_sessions` table (JSONB array)
- Loaded via `SessionStore.get_session_history()` with `max_messages=10`
- Multi-turn recall verified across sessions

### Persistent User Context
- `user_context` table: `context_type` + `context_key` + JSONB value
- Portfolio holdings, strategy preferences, watchlist
- 5-minute cache on Vercel, injected into every request

### Dream Memory
- `torq_memory` table with importance scoring (0.0-1.0)
- IRS tax knowledge (4 rows: deductions, entity_structure, rates_and_limits, citations)
- Injected into system prompt via `_load_dream_memories()`

### Fine-Tuned Local Model (prince-flowers V4)
TORQ AI's primary local model is a fine-tuned Qwen3-8B trained on 8,381 examples of TORQ advisory identity, reasoning patterns, and domain vocabulary.
- **Base model:** Qwen3-8B (Q4_K_M quantization via llama.cpp)
- **Training data:** 8,381 curated examples covering advisory analysis, market commentary, document review, drafting, and run orchestration
- **Serving:** Ollama on Railway, exposed as Tier 1b in the L27 router
- **Identity:** Inherits TORQ AI system prompt, calibrated for structured JSON output with confidence scoring
- **Model file:** `prince-flowers-model/` (Modelfile, training data, export scripts)

### Multi-Agent Development Harness
TORQ Console uses a 3-agent harness for structured development tasks:
- **Agent 2 (Architect):** Opus — analyzes requirements, produces build specs with acceptance criteria
- **Agent 1 (Builder):** GLM — implements specs precisely, writes build results with evidence
- **Agent 3 (Verifier):** Sonnet — validates output against specs, produces pass/fail verdicts
- **Artifacts:** `.torq/artifacts/01_architect/`, `.torq/artifacts/02_builder/`, `.torq/artifacts/03_verifier/`
- **Status tracking:** `.torq/artifacts/status/harness_status.json` with state machine (architect_complete → builder_complete → complete)
- **Launcher:** `torq-harness.cmd` for one-click full loop automation

### Web Search
- Claude native `web_search_20250305` tool on Railway + Anthropic fallback path
- TORQ AI answers real-time market and news queries

### Web Search Gate
Railway web search conditionally enabled — only fires for queries that need real-time data (`market_insight`, `standard_chat`). Draft, document review, advisory, and timeline queries skip web search entirely. Reduces input tokens by ~23-38% on non-market calls.

### Slack Integration
Incoming webhook integration for real-time notifications.
- "Send to Slack" button in Draft workspace alongside PDF/DOCX/MD exports
- Block Kit formatted messages with render-type-specific styling
- L25 governance parameter changes alert to Slack automatically
- Workspace events logged for every Slack export
- Graceful degradation when `TORQ_SLACK_WEBHOOK_URL` not set

Set `TORQ_SLACK_WEBHOOK_URL` in Railway + Vercel to activate.

### Adaptive Response Depth
TORQ AI matches response depth to query complexity:
- Simple questions: concise 2-4 paragraph answers
- Complex multi-part questions: comprehensive structured analysis
- Long document pastes (>1000 chars): proportional depth with full reasoning
- Deep Mode triggers: "deep dive", "ultrathink", "full analysis" produce 5,000+ character exhaustive analysis with bull/base/bear scenarios, contrarian views, and decision matrices

### Learning Loop
- `render_decisions` table: persists every classification decision
- `learning_events` table: persists every interaction for learning context
- Writes use httpx REST API with 3s timeout on Vercel
- Agent reads recent learning context into system prompt

---

## Frontend Architecture
Built from [PRD v3.0 Complete Build Specification](docs/PRD_v3.0_Complete_Build_Specification.pdf) across 8 phases.

### Shell Layout

[IconRail 56px] [WorkspaceHost flex-1] [ContextPanel 320px conditional] WorkspaceHost = WorkspaceHeader + CommandSurface + ModeWorkspaceHost + AgentActivityBar

### Renderer Registry
```typescript
const RENDERER_REGISTRY = new Map<RenderType, RendererConfig>();
// advisory_brief → AdvisoryCanvas + AdvisoryRail
// market_insight → MarketCanvas + MarketRail
// document_review → DocumentCanvas + DocumentRail
// draft_output → DraftCanvas + DraftRail
// run_timeline → RunTimeline + RunRail
// standard_chat → ChatThread + GenericRail (fallback)

Map-based dispatch (no switch statements). Unknown types fall back to standard_chat.

Domain Rails

Rail	Data Sources
AdvisoryRail	L12 EpistemicArtifactPublisher, LocalQualificationEngine, ContradictionManager + Synthesis
DocumentRail	L12 EpistemicAuditService, FederatedClaimRegistry + Risk synthesis
MarketRail	L12 signals + market data hooks
DraftRail	Templates, version history, export gating
RunRail	Teams (TeamExecutionCard, RoundTimeline, RoleRoster, DecisionSummary)

---

Platforms

Platform	URL / ID	Purpose
GitHub	github.com/pilotwaffle/TORQ-CONSOLE	Source (main branch)
Vercel	torq-console.vercel.app	Frontend + API routes (auto-deploys from main)
Railway	ROOT railway_app.py via start_railway.py	Backend intelligence + enforcement
Supabase	npukynbaglmcdvzyklqa	PostgreSQL (enforcement_events, learning_events, render_decisions, chat_sessions, user_context, torq_memory, torq_config, torq_model_usage, torq_session_metadata)

Request Flow

1. Frontend chatStreaming.ts calls /api/chat/v2 (Vercel, non-streaming)
2. api/index.py classifies intent, loads user context + dreams + history
3. draft_output → Vercel bypass (fast, prepends _SYSTEM_PROMPT)
4. All others → Railway proxy (connect=10s, read=120s)
5. Railway runs enforcement, calls Anthropic Claude, returns structured response
6. Fallback: if Railway fails, Vercel calls Anthropic directly (_chat_anthropic, 170s cap)

---

Environment Variables

Required

ANTHROPIC_API_KEY= # Claude API key
SUPABASE_URL= # Supabase project URL
SUPABASE_SERVICE_ROLE_KEY= # Supabase service role key

Railway Backend

RAILWAY_URL= # Railway deployment URL
GLM_API_KEY= # GLM-4-Flash for L22.5 context compaction

Integrations

TORQ_SLACK_WEBHOOK_URL= # Slack incoming webhook (enables Slack integration)
ZHIPU_API_KEY= # Z.AI API key for GLM-4.7-Flash context compaction (System B)

Optional (Tier 3 Cost Optimization)

TORQ_TIER3_ENABLED=true
TORQ_TIER3_PROVIDER=glm
TORQ_TIER3_MODEL=glm-4.7-flash

---

Quick Start

# Clone
git clone https://github.com/pilotwaffle/TORQ-CONSOLE.git
cd TORQ-CONSOLE
# Backend
pip install -r requirements.txt
cp .env.example .env # Edit with your API keys
python start_railway.py
# Frontend (separate terminal)
cd frontend && npm install && npm run dev

---

Timeout Chain (End-to-End: 180s)

Component	Timeout
Frontend abort	180s
Vercel maxDuration	180s
Railway proxy (connect/read)	10s / 120s
_chat_anthropic cap	170s
Fallback budget	max(170 - elapsed, 30)
Railway Anthropic httpx	180s

---

Telemetry

TORQ Console tracks system health across multiple tables:

Table	Purpose
workspace_events	User interaction telemetry
render_decisions	Classifier routing log
torq_session_metadata	Session health, cache, frustration
torq_model_usage	Token costs across all providers
torq_config	Runtime governance parameters (8 keys)
torq_config_audit	Append-only governance change log
torq_enforcement_log	Enforcement + fast path decisions
torq_memory	Dream System persistent memories
chat_sessions	Chat history per session
learning_events	Interaction history for learning context
user_context	Portfolio holdings, strategy preferences, watchlist
drift_metrics	Classifier drift scores and anomaly detection
phase_d_rollback_watchers	Threshold reset audit trail
run_recommendations	Recommendation engine output
agent_tasks	Multi-agent harness task tracking
experience_records	Experience capture for cognitive learning

---

Cost Optimization

Optimization	Impact
Prompt caching	69% to 13% cache miss rate
Dream memory cache	Per-session 5-min TTL, prefix stable
Web search gate	23-38% input token reduction
Draft direct bypass	$0.118/call vs $0.229 fallback
Conversation guards	20 msg / 40K char cap per session
Classifier truncation	First 500 chars only

---

Tagged Releases

• v0.30.0 — L25 Phase C Vocabulary Expansion, L27 4-tier router, prince-flowers V4, Phase D monitoring, TORQ AI branding
• v0.29.0 — L25 Runtime Governance (audit log, validation, risk classifier, fast path)
• v0.28.1 — L22.5 System B Context Pipeline (GLM compaction, 150K threshold)
• v0.28.0 — L22.5 Session Intelligence (frustration, tokens, cache, memory-as-hint)
• v0.27.0 — Multi-model cost routing (Tier 3 GLM-4-Flash), render decision persistence, learning loop

---

Running Tests

# Backend tests
pytest
# Enforcement tests (125+)
PYTHONPATH=. pytest tests/test_enforcement/ tests/layer21/ -v
# Frontend build verification
cd frontend && npm run build

---

Project Structure

api/index.py # Vercel serverless — classifier, routing, bypass, fallback
railway_app.py # Railway backend — enforcement, LLM, web search (ROOT entrypoint)
start_railway.py # Railway start script → uvicorn railway_app:app
torq_console/
├── agents/torq_prince_flowers/ # Prince Flowers agent + classifier.py
├── integrations/ # slack.py (Slack webhook connector)
├── intelligence/ # context_pipeline.py (L22.5)
├── risk/ # classifier.py (L25 risk levels + fast path)
├── enforcement/ # policy.py, kairos_tick.py, shadow mode, activation
├── layer12-21/ # Epistemic intelligence through historical strategy
├── mission_graph/ # Mission planning and execution
├── teams/ # Multi-agent debate and decisions
└── safety/ # Safety manager with L21 enforcement hook
frontend/src/
├── features/ # Advisory, Market, Documents, Drafts, Runs pages
├── components/
│ ├── shell/ # IconRail, WorkspaceHeader, ModeWorkspaceHost
│ ├── renderers/ # RendererRegistry, ChatThread, types
│ ├── right-rail/ # 5 domain rails + GenericRail
│ ├── command/ # CommandInput, CommandPalette
│ └── chat/ # ChatWindow, ChatMessage (demoted)
├── services/ # chatStreaming.ts, normalizeResponse.ts, telemetry
├── state/ # Zustand stores (session, appShell, workspace, etc.)
├── utils/ # docxExporter.ts
└── router/ # Work-type routes + /system/* legacy routes

---

Build Summary

Phase	Deliverable	Files
0	Backend Contract (StructuredResponse, normalizeResponse, /api/chat/v2)	2
1	Shell Hardening (AppShell, IconRail, WorkspaceHeader, routes)	6
2	Workspace Split + L12 Wiring (5 pages, 4 hooks, 5 stores)	14
3	Renderer Registry (Map dispatch, ChatThread fallback)	3
4	Domain Rails (5 rails + GenericRail, all wired to L12/synthesis/teams)	6
5	Realtime Bridge (event normalization, store dispatch)	3
6	Command Engine (keyword intent, mode suggestions, palette upgrade)	4
7	Polish + Mobile (skeletons, responsive, enforcement header, export, a11y, errors)	8

---

Deployment

Vercel (Frontend + API Routes)

Auto-deploys from main branch. Config in vercel.json. maxDuration: 180.

Railway (Backend)

Config in railway.json. Start: python start_railway.py. Entrypoint: ROOT railway_app.py.

Important: torq_console/railway_app.py is STALE — do not edit.

---

Contributing

Contributions welcome! Please see docs/CONTRIBUTING.md for guidelines.

---

License

MIT License — see LICENSE for details.

---

Acknowledgments

TORQ Console builds on excellent work by:

• Anthropic (Claude API)
• Supabase (PostgreSQL + real-time)
• ZhipuAI (GLM-4-Flash for context compaction)
• React, Zustand, TanStack Query, Tailwind CSS, docx-js
• The open-source AI community