VITRUVYAN CORE V1.0 — STATE OF THE ART

Date: 2026-02-15T23:45Z (February 15, 2026 — 23:45 UTC)
Release Readiness Score: 97.5% (target 90%)
Purpose: Canonical reference document for AI analysis of the Vitruvyan Core codebase
Certification: Final Closure Certification PASSED (5/5 sections) — see V1_FINAL_CLOSURE_CERTIFICATION_FEB15_2026.md

1. MISSION

Vitruvyan Core is a domain-agnostic epistemic operating system that provides:

• A governed cognitive pipeline (LangGraph orchestration, Sacred Orders)
• Pluggable domain verticals via configuration and runtime plugins
• A solid, secure, scalable framework that never embeds domain-specific assumptions

The core must remain pure infrastructure — any domain (finance, healthcare, legal, research) plugs in through:

1. domains/<domain>/ — intent config, prompts, slot definitions
2. contracts/ — ABCs, protocols, base state (the extensibility surface)
3. Environment variables — all operational tuning without code changes

2. ARCHITECTURE OVERVIEW

2.1 Repository Layout

vitruvyan_core/
├── core/
│   ├── agents/               # Singleton gateways to external systems
│   │   ├── postgres_agent.py     # PostgreSQL (ThreadedConnectionPool)
│   │   ├── qdrant_agent.py       # Qdrant vector DB
│   │   ├── llm_agent.py          # LLM gateway (OpenAI, pluggable via ILLMProvider)
│   │   └── alchemist_agent.py    # Schema migrations (Alembic)
│   ├── cache/
│   │   └── mnemosyne_cache.py    # Multi-tier vector-aware cache (Redis SCAN)
│   ├── cognitive/                # Perception Sacred Orders
│   │   ├── babel_gardens/            # Language detection, NLU, translation
│   │   └── pattern_weavers/          # Ontology mapping, pattern classification
│   ├── contracts/                # PUBLIC EXTENSIBILITY SURFACE
│   │   ├── __init__.py               # Single import point for all ABCs/protocols
│   │   └── llm_provider.py           # ILLMProvider — runtime_checkable Protocol
│   ├── governance/               # Governance Sacred Orders
│   │   ├── codex_hunters/            # System discovery, maintenance
│   │   ├── memory_orders/            # Coherence analysis, RAG
│   │   ├── orthodoxy_wardens/        # Validation, audit, invariant enforcement
│   │   └── vault_keepers/            # Archival, persistence, snapshots
│   ├── llm/
│   │   ├── cache_api.py              # LLM response caching + cost tracking
│   │   ├── cache_manager.py          # Redis-backed LLM cache (SCAN-only)
│   │   └── prompts/                  # PromptRegistry (domain-aware)
│   ├── logging/
│   │   └── audit.py                  # Structured audit logger (Redis Stream + optional PG)
│   ├── middleware/
│   │   └── auth.py                   # Opt-in AuthMiddleware (Bearer token)
│   ├── neural_engine/            # Computation engine (batch scoring)
│   ├── orchestration/            # LangGraph pipeline + plugin system
│   │   ├── base_state.py             # BaseGraphState (37 fields, extensible)
│   │   ├── execution_guard.py        # Hard timeout enforcement (ThreadPoolExecutor)
│   │   ├── graph_engine.py           # GraphPlugin, NodeContract, GraphEngine
│   │   ├── parser.py                 # Parser ABC, BaseParser, ParsedSlots
│   │   ├── intent_registry.py        # IntentRegistry (domain plugin pattern)
│   │   ├── route_registry.py         # Route definitions
│   │   ├── entity_resolver_registry.py
│   │   ├── execution_registry.py
│   │   └── langgraph/                # Graph nodes, runner, flow
│   │       ├── graph_runner.py           # Entry point (lazy init)
│   │       ├── graph_flow.py             # Pipeline wiring
│   │       └── node/                     # 15+ cognitive nodes
│   ├── synaptic_conclave/        # Cognitive Bus (Redis Streams)
│   │   ├── transport/
│   │   │   ├── streams.py                # StreamBus (TLS, password, env-configured)
│   │   │   └── dlq.py                    # Dead Letter Queue (retry tracking, idempotency)
│   │   ├── events/                   # TransportEvent, CognitiveEvent, EventAdapter
│   │   ├── plasticity/               # Adaptive learning
│   │   └── governance/               # Bus-level governance
│   └── vpar/                     # Vitruvyan Probabilistic Assessment
├── domains/
│   ├── finance/                  # Reference vertical (intent_config, prompts, slots)
│   ├── energy/                   # Test vertical (grid, renewables) — V1.0 certification
│   ├── facility/                 # Test vertical (building mgmt) — V1.0 certification
│   ├── dummy_test/               # Minimal test vertical — V1.0 certification
│   ├── base_domain.py            # Domain ABC
│   ├── aggregation_contract.py
│   ├── explainability_contract.py
│   └── risk_contract.py
services/                         # 12 FastAPI microservices (LIVELLO 2)
├── api_graph/                    # LangGraph orchestration service
├── api_babel_gardens/            # NLU service
├── api_codex_hunters/            # System maintenance service
├── api_memory_orders/            # Coherence + RAG service
├── api_orthodoxy_wardens/        # Governance service
├── api_pattern_weavers/          # Ontology service
├── api_vault_keepers/            # Archival service
├── api_neural_engine/            # Computation service
├── api_embedding/                # Vector embedding service
├── api_conclave/                 # Bus management service
├── api_mcp/                      # Model Context Protocol service
└── redis_streams_exporter/       # Prometheus metrics exporter

2.2 Sacred Orders (Epistemic Hierarchy)

Each Sacred Order follows the mandatory two-level pattern:

• LIVELLO 1 (pure domain): 10 directories, zero I/O, pure Python, testable standalone
• LIVELLO 2 (service): FastAPI, Docker, adapters, main.py < 100 lines

2.3 LangGraph Pipeline (Cognitive Kernel)

parse → intent_detection → weaver → entity_resolver → babel_emotion
  → semantic_grounding → params_extraction → decide → [route branches]
  → output_normalizer → orthodoxy → vault → compose → can → [advisor] → END

Route branches from decide node:

• dispatcher_exec → direct execution
• semantic_fallback → Qdrant vector search
• llm_soft → conversational LLM (cached)
• slot_filler → missing parameter negotiation
• codex_expedition → system maintenance
• llm_mcp → MCP tools (when USE_MCP=1)

Intent detection is 100% domain-agnostic: domains register via INTENT_DOMAIN env var and domains/<domain>/intent_config.py.

3. EXTENSIBILITY CONTRACTS

3.1 Plugin Surface (contracts/)

from contracts import (
    # Graph state
    BaseGraphState, GraphStateType,
    ESSENTIAL_FIELDS, INTENT_FIELDS, LANGUAGE_FIELDS, EMOTION_FIELDS,
    ORTHODOXY_FIELDS, VAULT_FIELDS, TRACING_FIELDS, WEAVER_FIELDS,
    CAN_FIELDS, ALL_BASE_FIELDS,
    get_base_field_count, is_base_field, get_domain_fields,
    # Engine
    GraphPlugin, NodeContract, GraphEngine,
    # Parser
    Parser, BaseParser, ParsedSlots,
    # LLM
    ILLMProvider,
)

3.2 How a Domain Vertical Plugs In

1. Intent detection: Create domains/<domain>/intent_config.py with create_<domain>_registry(). Set INTENT_DOMAIN=<domain>.
2. Prompts: Register domain prompts via PromptRegistry.register_domain() in core/llm/prompts/registry.py.
3. Graph state: Extend BaseGraphState with domain-specific fields — the core's 37 fields are inherited automatically.
4. LLM provider: Implement ILLMProvider protocol (5 methods: complete, complete_json, complete_with_messages, complete_with_tools, acomplete) to swap OpenAI for any provider.
5. Entities: Define domain entities that flow through validated_entities contract.

3.3 Domain-Agnostic Guarantees

• No finance/trading terms in core code (legacy remnants fully purged from active code paths)
• Intent detection, emotion detection, entity extraction all delegate to LLM as primary engine (regex fallback only)
• domains/finance/ exists as reference implementation, zero imports from core into it
• Multi-vertical proven: 4 domains (finance, energy, facility, dummy_test) load dynamically via importlib, with 0 naming collisions and full config isolation

4. SECURITY POSTURE

4.1 Credentials & Secrets

4.2 Authentication

• Middleware: core/middleware/auth.py — opt-in AuthMiddleware
• Activation: VITRUVYAN_AUTH_ENABLED=true + VITRUVYAN_AUTH_SECRET or VITRUVYAN_KEYCLOAK_URL
• Coverage: All 11 FastAPI services have middleware integrated
• Default: Disabled (zero overhead) — enables gradual rollout
• Features: Bearer token validation, configurable public paths, CORS preflight passthrough, custom validator injection
• Tests: 14 unit tests in tests/test_auth_middleware.py

4.3 Transport Security

4.4 Audit Logging

• Module: core/logging/audit.py — structured AuditLogger with mandatory schema
• Backends: Python logger (always) + Redis Stream (default) + PostgreSQL (optional)
• Stream: vitruvyan:audit (configurable via AUDIT_STREAM, max length AUDIT_STREAM_MAX_LEN)
• Schema: AuditEvent dataclass — timestamp, event_id, correlation_id, node_id, plugin_id, execution_time_ms, status, error_code, metadata
• Control: AUDIT_ENABLED=true (default on), AUDIT_POSTGRES_ENABLED=false (opt-in)
• Emitted automatically on pipeline timeout by graph_runner.py

4.5 Configuration Hygiene

• Zero load_dotenv() in all production code — core and services
• Removed from all service entrypoints during hardening + final certification
• Prevents .env files from silently overriding production environment variables

4.6 CORS

• All 11 FastAPI services have CORSMiddleware configured
• Default: http://localhost:3000 (restrictive)
• Configurable via CORS_ORIGINS env var (comma-separated)

5. SCALABILITY

5.1 PostgreSQL

5.2 Redis

KEYS residual: only scripts/audit_streams_topology.py (CLI tool) and test fixtures — non-production.

5.3 LangGraph

5.4 LLM Rate Control

5.5 Resilience & Fault Tolerance

6. CONFIGURATION REFERENCE

All operational values are configurable via environment variables. No code changes required for tuning.

6.1 Infrastructure

6.2 LLM & AI

6.3 Cognitive Bus (Synaptic Conclave)

6.4 Orchestration

6.5 Security

6.6 Execution Control

6.7 Dead Letter Queue

6.8 Audit Logging

7. SERVICES MATRIX

All services follow the SERVICE_PATTERN.md convention: main.py < 100 lines, adapters/, api/routes.py, config.py.

8. SACRED ORDERS CONFORMANCE

All 6 Sacred Orders have complete LIVELLO 2 service implementations with adapters, routes, and models.

9. INVARIANTS (NON-NEGOTIABLE RULES)

These rules are enforced across the codebase and must be preserved by any future work:

1. Core stays generic — no domain logic in vitruvyan_core/core/. Domains plug in via domains/ and contracts/.
2. No cross-service imports — services communicate via REST or StreamBus events only.
3. Agents for all external access — PostgresAgent, QdrantAgent, LLMAgent only. No raw psycopg2.connect(), qdrant_client.QdrantClient(), or from openai import OpenAI.
4. No secrets in source — all credentials via env vars with ${PLACEHOLDER} in docs.
5. Streams, not Pub/Sub — Redis Streams is canonical transport. Acknowledge after handling. Generator consumption.
6. Bus is payload-blind — transport layer never inspects, routes, or correlates event content.
7. Validated lists are authoritative — if client sends validated_entities, backend respects it (including explicit []).
8. LLM-first, never heuristics-first — intent, emotion, entity extraction delegate to LLM. Regex is only fallback.
9. No load_dotenv() anywhere — configuration exclusively via environment variables. Zero load_dotenv() calls in core and services.
10. Failed events to DLQ — events exceeding DLQ_MAX_RETRIES must be routed to the Dead Letter Queue, not left in PEL indefinitely.

10. TESTING

Final Closure Certification (5 sections, all passed):

• S1 Structural: 256 files AST-scanned, 0 import violations
• S2 Performance: Neural Engine O(n) scaling, 24K entities/sec, no memory leaks
• S3 Concurrency: 50 concurrent pipelines, fault injection, no deadlocks
• S4 Multi-Vertical: 4 domains loaded dynamically, 0 collisions
• S5 Security: 642 files secret-scanned, 8/8 cold boot imports, 0 load_dotenv()

Full report: docs/planning/V1_FINAL_CLOSURE_CERTIFICATION_FEB15_2026.md

Hardening test breakdown (29 tests, 6 classes):

• TestNodeExecutionGuard — 7 tests (success, timeout, exception, per-call override, env config, singleton, state preservation)
• TestDeadLetterQueue — 8 tests (retry tracking, DLQ routing, idempotency, serialization, listing, health, ACK)
• TestRedisKeysElimination — 2 tests (source code scan verifying scan_iter usage)
• TestAuditLogger — 9 tests (schema, error codes, JSON serialization, Redis fields, backends, disable, singleton, metadata)
• TestLoadDotenvRemoval — 2 tests (source code scan verifying no load_dotenv in core)
• TestTraceIdFullLength — 1 test (full UUID4 = 36 chars)

11. KNOWN RESIDUAL ITEMS (Low Priority, Non-Blocking)

These items are documented for completeness. None block V1.0 release.

12. RELEASE READINESS SCORE

13. COMMIT HISTORY (Remediation Arc)

Score progression: 79% → 96% (remediation) → 97% (hardening) → 97.5% (final closure).

All phases completed (0, 1, 2, 3, 4, 5) + Hardening + Coupling + Structural Cert + Final Closure Certification.