SDK
Build with the kernel. Not around it.
Python agents, a CLI, and REST APIs. Everything you need to wire your domain logic into the cognitive stack — without touching kernel internals.
Python Agents
Four agents cover all external access — LLM, database, vectors, and events. Import them. Call methods. The agents handle connection pooling, retries, and configuration.
LLMAgent
from core.agents.llm_agentCentralized LLM gateway. Single-turn, multi-turn, JSON-structured output, function calling. Model-agnostic — swap providers via env vars.
PostgresAgent
from core.agents.postgres_agentTyped PostgreSQL access with connection pooling, transactions, and query builder. All persistence goes through this — never raw psycopg2.
QdrantAgent
from core.agents.qdrant_agentVector storage and semantic search. Manages collections, embeddings, and filtered retrieval. The memory layer for your vertical.
StreamBus
from core.synaptic_conclave.transport.streamsRedis Streams-based event bus. Publish and consume domain events asynchronously. Payload-blind — the bus never inspects your data.
Example
# Your vertical's consumer — pure domain logic
from core.agents.llm_agent import get_llm_agent
from core.agents.qdrant_agent import QdrantAgent
llm = get_llm_agent()
qdrant = QdrantAgent()
# Semantic search + LLM reasoning in 3 lines
context = qdrant.search("collection", query, limit=5)
answer = llm.complete(
prompt=f"Given {context}, answer: {query}"
)CLI Reference
The vit CLI manages the full lifecycle — from bootstrapping the kernel to installing packages, upgrading versions, and rolling back if something breaks. Zero installation required: the wrapper auto-configures your PATH and bash autocomplete.
Core
| vit status | Show kernel version, health, and running services |
| vit setup | Bootstrap a fresh installation |
| vit logs <service> | Tail logs from a kernel service |
| vit config set <key> <value> | Update kernel configuration |
Verticals
| vit vertical create <name> | Scaffold a new domain vertical with manifest + structure |
| vit vertical deploy <name> | Deploy vertical into the running kernel |
| vit vertical list | List installed verticals and their status |
Packages
| vit install <package> | Install a .vit package (service, order, vertical, or extension) |
| vit remove <package> | Remove an installed package and its dependencies |
| vit list [--all] | List installed packages or all available packages |
| vit search <query> | Search the package registry |
| vit info <package> | Show package details, dependencies, and compatibility |
Updates
| vit update | Check for available kernel updates (read-only) |
| vit upgrade | Apply kernel upgrade with smoke tests and automatic rollback |
| vit plan | Preview upgrade plan without applying (dry-run) |
| vit rollback | Revert to the previous version via git snapshot |
| vit channel <stable|beta> | Switch update channel |
| vit release | Validate local release metadata |
Vertical Manifest
Every vertical starts with a vertical_manifest.yaml. It tells the kernel what your domain looks like, what it needs, and which components it implements.
The manifest is declarative — no code. The kernel reads it at deploy time and wires your vertical into the pipeline.
domain_namestringYour domain identifier (e.g. "healthcare", "legal")
domain_versionstringSemver version of your vertical
compatibility.min_core_versionstringMinimum kernel version required (e.g. "1.2.1")
compatibility.max_core_versionstringMaximum kernel version, supports wildcards (e.g. "1.x.x")
compatibility.contracts_majorintegerMust match the kernel's contract major version
compatibility.update_channelstringSubscribed channel: "stable" or "beta"
compatibility.smoke_tests_timeoutintegerSeconds to wait for smoke tests during upgrade (default: 300)
required_componentsobjectComponents your vertical must implement: intent_config, manifest, readme
optional_componentsobjectOptional modules: graph_plugin, governance_rules, slot_filler, entity_resolver_config
notifications.enabledbooleanEnable update notifications on startup
notifications.check_interval_hoursintegerHow often to check for updates (default: 24)
REST APIs
Every kernel service exposes HTTP endpoints. Use them from external systems, dashboards, or custom frontends. All services run behind Docker with standard health checks.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/graph/invoke | Execute the cognitive pipeline with a user query |
| GET | /api/memory/search | Semantic search across the kernel's memory layer |
| POST | /api/embedding/encode | Generate embeddings for text or documents |
| GET | /api/conclave/streams | List active event streams and consumer groups |
| GET | /health | Service health check (available on every microservice) |
Package System
Everything in Vitruvyan is a package. Services, Sacred Orders, verticals, extensions — all distributed as .vit manifests with declared dependencies, health checks, and smoke tests.
service-graphMicroservices that plug into the kernel (graph, embedding, MCP, neural engine).
order-babel-gardensSacred Order modules — cognitive primitives (Babel Gardens, Pattern Weavers).
vertical-financeDomain-specific intelligence layers built on the kernel.
extension-mcp-toolsOptional capabilities that extend the kernel without modifying core.
Dependency resolution
The package manager resolves dependencies via topological sort, detects version conflicts and port collisions before installation, and runs health checks after deployment. Removals cascade through the dependency graph — nothing gets orphaned.
Two tiers
Core tier
Managed by vit upgrade. Kernel infrastructure — you don't install these individually.
Package tier
Managed by vit install. Services, orders, verticals, extensions — install what you need.
Update & Upgrade
Kernel upgrades are safe by design. The update engine checks compatibility against your vertical manifests, runs smoke tests, and snapshots the current state before applying. If anything fails, it rolls back automatically.
Check
vit updateFetches available releases from GitHub (Releases API with Tags fallback). Compares against your current version and vertical compatibility ranges. Read-only — nothing changes.
Plan
vit planGenerates an upgrade plan: prerequisites, breaking changes, affected verticals, smoke test schedule. Review before committing.
Upgrade
vit upgradeCreates a git snapshot of current state, applies the update, rebuilds affected containers, runs smoke tests. If tests fail within the configured timeout, automatic rollback.
Rollback
vit rollbackReverts to the pre-upgrade snapshot. Works even if the upgrade partially succeeded. Your data and configuration are preserved.
CI enforcement
The release blocker runs in CI before every publish. It validates all vertical manifests against the new version, checks contract compatibility, and blocks the release if any vertical would break. Violations are not warnings — they are hard failures.
Contracts
The kernel enforces a contract system. Your vertical declares what it implements, and the kernel validates conformance at deploy time. No runtime surprises.
Vertical Contract V1
Required interfaces every vertical must implement: intent config, entity definitions, manifest schema.
Conformance Checklist
Automated validation that your vertical meets all contract requirements before deployment.
Event Envelope
Standard event format for the cognitive bus. TransportEvent (bus-level) and CognitiveEvent (consumer-level).
Update System Contract
Governs versioning, publishing, compatibility constraints, upgrade validation, and rollback procedures.
Package Manager Contract
Defines the .vit manifest format, package types, dependency resolution, and installation lifecycle.
CI Release Blocker
Blocks any release that would break existing vertical compatibility. Runs automatically in the pipeline.
Start building
Install the kernel, scaffold a vertical, and use these APIs to wire your domain logic into the cognitive pipeline.