SystemArchitecture
SAMI is a multi-layered AI system built on precise planning and stage-gated consensus. Every stage must persuade the council before code is written.
System Overview Specification
Client Layer
Industry-standard editor
Live discussion view
Integrated shell
Live Streaming
Multi-Agent Orchestration
Agent Workflows
Multi-model council
Voting Protocol
Code Intelligence
Semantic understanding
Functions/Classes
Smart Splitting
Hybrid Context Engine
Vector context
Keyword Search
Multi-retriever fusion
Cross-encoder scoring
Model Execution Layer
Top-tier reasoning models
Extended-context generation models
Multimodal vision models
Open-weights via managed providers
Reasoning-optimised code models
Core Modules
The core pillars of the SAMI architecture
Hybrid Context Engine
Hybrid project retrieval for source-aware context
Code Intelligence
AST-based semantic code understanding
Multi-Agent Orchestration
Multi-model council: every model reviews with equal weight and votes
Model Gateway & Managed Models
Cloud API Routing + Managed Model Catalog
Smart Indexing
AST-based Chunking + Symbol Metadata
Security & Privacy Layer
Managed infrastructure with zero cloud persistence
The Council
Every model you pick is an equal-vote Guardian for the whole run. Lead and Writer are duties that move between Guardians stage by stage — never a higher rank. A no never ends the run: it loops back until the council reaches a genuine yes.
Equal council, rotating duties
Every selected model is an equal-vote Guardian for the whole run. Lead and Writer are duties that move between Guardians as the pipeline advances — never a higher rank.
The code stage — the Writer drafts the implementation while the council critiques.
Guardian. Every selected model. Equal vote, every stage, the whole run.
Lead. A per-stage duty: coordinates the discussion and announces the outcome — votes with equal weight. It moves to a different Guardian every stage.
Writer. A per-stage duty: the only model that writes code or runs commands, at the build stages. It also rotates between Guardians.
Binary vote. Each Guardian votes Yes or No — there is no third option. A No never ends the run: it loops back to deliberation, the council brings counter-arguments, and it resolves into a genuine Yes.
Any Guardian can pause the Writer mid-work
Supervision is not a one-time gate at the end of a stage. While the Writer is producing or changing code, any Guardian that spots a problem can raise an objection before the next action is taken. The objection routes straight back to deliberation — the council brings counter-arguments and alternatives, and the work only resumes once the concern resolves into a genuine yes.
Hybrid-Search Pipeline
From raw query to hyper-optimized AI context
Query Analysis Firewall
Intent detection classifies: Structural? Conceptual? Hybrid?
Vector Search Engine
Semantic retrieval for source-aware context
Keyword Search Engine
Exact-symbol retrieval for names, APIs, and file paths
Rank Fusion
Rank fusion, scoring, and a compact result set for the council
Optimized Context Block
Max 8K tokens. Structural + semantic information merged and compressed.
Context Flows Into the Council
The optimized context block is not the finish line — it is the start. From there, context flows into every stage: a shared baseline every stage reads, a per-stage slice pulled on top, and cross-stage recall so any model can look back at what any other Guardian said earlier in the run.
Hybrid retrieval blends semantic, keyword and code intelligence into one project-context stream the council can draw on.
- Shared baseline context — every stage reads it
- Per-stage context slice — pulled on top into each stage
- Cross-stage recall — look back at earlier council context
The Iterative Workflow
A loop with human-in-the-loop validation — step by step until the finished product.
The 7-stage council pipeline
One council, seven stages. Every model is an equal-vote Guardian the whole run; the Lead and Writer duties move between them stage by stage.
Actually runs the project; any failure goes back to the council and is worked to a genuine pass before finishing.
- Read
- Docs + Web
- Write / Edit
- Run
- Read
- Docs + Web
- Write / Edit
- Run
Read & research belong to every Guardian. Write & Run belong to the Writer only, and only at Maverick (04) and Optimizer (05).
- LeadA per-stage duty: coordinates the discussion and announces the outcome — votes with equal weight. It moves to a different Guardian each stage.
- WriterA per-stage duty: the only model that writes code or runs commands, at the build stages.
01 Connector — Clarification Q&A Loop
Interactive question-and-answer loop between the council and the user — before any artifact is produced
Flow: The council collects open questions (missing information, scope ambiguities) and presents them to the user in a single batch. The user answers inline until every Guardian agrees the task is fully understood — the council itself decides when the scope is clear, with no fixed round limit (only your run budget or an explicit cancel bounds it). Only then does Stage 02 begin.
Scope clarified — ready for planning
02 Strategist — Architecture Planning
Create the master plan, choose patterns, align on architecture
Action: The agents shift to planning mode. Based on context, they design folder structures and generic interfaces, resulting in a Master Plan.
03 Architect — Structural Logic
Translate the master plan into interfaces, schemas, contracts, and module boundaries
Building the actual scaffolding. Interfaces, classes, and empty functions are drafted to enforce strict type safety across the entire system.
04 Maverick — Code Draft
One model writes the binding code draft; all others review and raise change requests
Only one model (Writer) writes the binding code draft. All other Guardians critique the direction, sketch alternatives in prose (no code), and raise change requests to the Writer. One model (Lead) coordinates the flow. Contributions arrive in arrival order — no round-robin.
05 Optimizer — Challenge & Revision
All Guardians challenge the draft; the strongest optimization path is adopted
Action: All reviewing agents challenge the draft with performance and correctness feedback, the coordinating agent selects the final optimization path, and the authoring agent records the accepted revision.
06 Guardian — Red Teaming
Adversarial review: actively surface vulnerabilities, edge cases, and unsafe assumptions
Veto Checkpoint Required: Guardians actively attempt to break the code (SQLi, race conditions, stale state). Voting is binary — yes or no. A model with any doubt votes no and must explain why; there is no separate concern or abstain vote.
How a NO resolves
A NO is never dropped or rubber-stamped. The Guardian that votes no must state why; the council then deliberates — surfacing counter-arguments and alternatives — until the objection resolves into a genuine yes.
Only run-budget exhaustion or the user cancelling the run advances a stage with an unresolved no, and in that case the final artifact carries an explicit unresolved-objection note visible in the War Room.
VETOES RESOLVED → Ready for Final Audit
07 Debugger — Execution-Verify Gate
A council that doesn't just agree — it runs the code
Iterative Refinement
Validation failed? - back to Stage 4 (Draft)
All review stages complete? - Ready for delivery
You Set the Autonomy
Three autonomy levels decide how much you approve along the way. They change the checkpoints you see — not the council. Multi-model supervision is always on at every level.
Guided
You confirm at each stage gate. Nothing advances to the next stage without your go-ahead.
Balanced
The council advances on its own through routine stages and pauses for your call on the decisions that matter.
Autonomous
The council runs the full pipeline end to end and surfaces the result. You stay in control and can step in at any time.
The council never switches off. Autonomy only governs how often the work pauses for your approval. Every stage is still reviewed and voted on by the full council, and a no still loops back to a genuine yes — even at the most autonomous level.
Technology Stack
Built with best-in-class frameworks and tools.
IDE Core
Vector Search
Code Intel
Orchestration
LLM Routing
Backend
Privacy & Security
Managed models. Ephemeral processing. No permanent cloud storage. Your data stays under your control.
Managed Embeddings
Code indexing runs through SAMI's managed infrastructure. Your data is processed ephemerally and never stored permanently.
Managed Provider Vault
Provider credentials are encrypted and isolated inside SAMI's managed infrastructure.
Managed Model Access
For maximum consistency: Use only the models SAMI offers in your plan, with routing and billing handled centrally.
Download SAMI
The multi-model council is ready for your project — get started with the desktop app.