The Self-Sovereign Personal/Professional AI Assistant
The Alluci Sovereign Agent is a self-sovereign, multi-agent computational runtime that serves as your primary personal and professional interface acting as your high-level digital assistant, orchestrating complex workflows, multi-step research, and multi-channel communications.
Alluci unifies local on-device intelligence with policy-driven cloud model federation—allowing you to harness frontier AI capabilities while your data, memories, workflows, and intellectual property remain cryptographically secured and physically under your control within a single Self-Sovereign Agentic Operating System.
The Sovereign Manifold acts as your central neural dispatch for all digital communications, workflows, and biometric state tracking. Rather than forcing you to jump between fragmented apps and isolated browser tabs, Alluci unifies your entire digital life under a single sovereign interface.
Every channel integration operates inside an isolated cryptographic Simplicial Vault bound to your VerusID, ensuring seamless multi-channel agency without cross-channel data leaks or unauthorized exposure across four core operational manifolds:
The Multi-Modal Synthesis & API Orchestration engine serves as Alluci’s unified control plane for generative tools, token routers, and cognitive services. Rather than locking you into a single closed ecosystem, Alluci provides policy-driven model federation—dynamically routing tasks across specialized foundation models, voice synthesis engines, and generative media tools while respecting your local privacy constraints and token budge.
The Polytope Manifold Architecture serves as the core cognitive blueprint governing how Alluci processes intelligence, preserves stateful memory, and executes multi-agent workflows.
Alluci is powered by a hybrid computational runtime—combining native Python execution engines with high-performance compiled C++ extensions and specialized topological kernels. This architecture pairs proactive cognition and a native Apple MLX engine driving on-device foundation model evaluation on Unified Memory with Non-Euclidean geometric manifold mapping and Betti signature context indexing across a stateful 4-Tier Memory System.
System execution is governed by a three-pillar action safety loop enforcing Lipschitz gradient smoothness and payload verification, integer simplicial boundary operators for Betti topology discrete manifold verification, high-frequency signal processing and harmonic lattice calculations, and cryptographic Simplicial Vault isolation encrypting credentials and bridge secrets via AES-256-GCM.
The Polytope Projection Network (PPN) serves as Alluci’s non-Euclidean geometric intelligence engine. Moving beyond traditional, hallucination-prone vector similarity lookups, PPN projects unstructured multi-modal data streams—text, biometrics, tool actions, and execution traces—into topologically stable geometric manifolds. Governed by algebraic topology and simplicial homology, PPN evaluates state continuity using Betti signatures ($\beta_0, \beta_1, \beta_2$), ensuring that cognitive operations maintain structural integrity across execution cycles.
SEC-005)ACE)_perform_ppn_check): Evaluates candidate task objectives and tool actions for topological tearing ($\Delta \beta$ norm spikes, entropy threshold breaches) before committing steps to execution pipelines.Structural Barcode Extraction: Distills complex problem-solving paths into compact, invariant topological barcodes.
Zero-Knowledge Swarm Broadcast: Broadcasts structural barcodes over the Verus P2P network, enabling federated multi-agent swarm intelligence without exposing raw prompt context or private user data.
The Discrete Projection Kernel (DPK) serves as the high-speed, zero-trust cryptographic gatekeeper of the Alluci execution runtime. Grounded in Kepler's Stella Octangula $S_8$ geometry (compound of dual regular tetrahedra $T_+ \cup T_-$ with 8 vertices, 12 edges, 8 faces, and central octahedron $O_6$), DPK validates state transition vectors ($\mathbf{x}_{t-1} \to \mathbf{x}_t$), enforcing topological boundary nilpotence, Euler characteristic invariants ($\chi = V - E + F$), and idempotent fusion projections before any tool or agent action executes.
dpk_kernel.cpp / ctypes), falling back to a pure Python implementation when hardware constraints dictate.TearingException, instantly halting execution to prevent state corruption or hallucinated loop cascades.AAP-003)PolytopeState.CalibrationManager to dynamically calibrate safety rejection thresholds based on execution history, affective tension ($\psi$), and active workspace permissions.is_override=True), allowing authorized users to bypass false-positive manifold halts while preserving audit logs.The Sovereign Topological State Space Subsystem (backend/topology/) formalizes Alluci's cognitive reasoning into a mathematically bounded 5-tuple $(W, X, \mathcal{J}, G, N)$ governed by rigorous algebraic topology operators:
┌────────────────────────────────────────────────────────┐
│ W (World Data Space) │
└──────────────────────────┬─────────────────────────────┘
│ P: W × X → [0,1]
▼ (Vietoris-Rips Filtration)
┌────────────────────────────────────────────────────────┐
│ X (Experience Simplicial Space) │
│ [Betti Invariants: β₀, β₁, β₂, β₃] │
└──────────────────────────┬─────────────────────────────┘
│ S: X × G × J → J
▼ (Simplicial CoT & Socratic Synthesis)
┌────────────────────────────────────────────────────────┐
│ J (J-Space Counterfactual Simulation Sandbox) │
│ Kepler S₈ Synthesis: T₊ ∪ T₋ → O₆ Kernel │
└──────────────────────────┬─────────────────────────────┘
│ D: J × G → [0,1]
▼ (Convex Hull Affordance)
┌────────────────────────────────────────────────────────┐
│ G (Action Affordance Envelope Space) │
│ [3D Risk Simplex & Sub-Agent Bounds] │
└──────────────────────────┬─────────────────────────────┘
│ A: G × W → [0,1]
▼ (Markov Trace & DPO Harvesting)
┌────────────────────────────────────────────────────────┐
│ N (Discrete Topological Barcode Clock Count) │
│ [Monotonic Pacing: N → N+1, Birth/Death Tracking] │
└────────────────────────────────────────────────────────┘
PMETFiltrationEngine): Samples multi-dimensional point clouds from $W$, constructs Vietoris-Rips complexes up to 2-skeleton (triangular faces), and extracts exact Betti invariants ($\beta_0$ connected components, $\beta_1$ 1-skeleton cycles, $\beta_2$ 2-voids).JSpaceSimulator): Evaluates multi-step counterfactual simulation traces, validating deductive reasoning steps as 2-simplices to ensure algebraic boundary nilpotence ($\partial_1 \circ \partial_2 = 0$). Reconciles constructive hypotheses ($T_+$) and critical skeptic critiques ($T_-$) into the central intersection kernel ($O_6$).ActionAffordanceEnvelope): Validates candidate execution vectors against sub-agent domain boundaries (Codi, Rocco, Admin) and bio-affective stress thresholds ($\psi \le 0.85$), ensuring destructive tasks are strictly intercepted by HITL governance.MarkovTraceEngine & DPOTripletHarvester): Executes verified actions, evaluates multi-step trajectories using the Schur complement Markov Trace operator ($\text{Tr}_A(P) = A + B(I-C)^{-1}D$), monitors Frenet-Serret curvature ($\kappa \le 5.0$), and records verified $(x, y_w, y_l)$ preference triplets for offline distillation.TopologicalBarcodeClock)The Action Verification Loop (AVL Gate) serves as Alluci’s zero-trust safety and payload verification engine. Functioning as an inline firewall between LLM generation outputs and tool execution adapters, the AVL Gate enforces a mathematical three-pillar security protocol. It prevents unauthorized code execution, prompt injections, and structural hallucinations by verifying cryptographic attribution, gradient smoothness limits, and topological continuity before any action payload is committed.
project_to_boundary): Projects near-boundary prompt violations back into admissible Lipschitz bounds, neutralizing prompt injection attacks without disrupting execution flow.verify_action_payload): Dynamically scales and clamps numeric tool parameters (top_k, limit, timeout, depth, steps, count, max_tokens) proportionally to available Lipschitz budget capacity.ExecutiveOrchestrator self-healing loop injects a high-priority <SECURITY_RUPTURE> prompt directive, instructing the agent to regenerate a safe, strictly bounded plan.HUMAN-IN-THE-LOOP REQUIRED mode, halting autonomous execution to preserve workspace integrity.CalibrationManager (avl_calibration_cache.json) to continuously track execution history, tool success rates, and affective tension ($\psi$).The Proactive Cognition Layer (PCL) serves as Alluci’s continuous background reasoning and autonomous intelligence engine. Architecturally distinct from passive event watchers or simple cron pollers, PCL operates as an autonomous cognitive loop—continuously observing system signals, constructing stateful world models, identifying execution opportunities, and executing proactive workstreams without requiring explicit user prompting.
OBSERVE → MODEL → DETECT → JUDGE → ACT)WorldModel snapshot persisted to SQLite database tables (pcl_world_snapshot).StalledGoalDetector, UnresolvedThreadDetector, HardwareAnomalyDetector, AffectiveStressDetector) to discover actionable tasks.ExecutiveOrchestrator or broadcasts non-intrusive administrative notifications via streaming WebSockets (JsonRpcGateway).ACE Integration)The PVT Manifold Health Monitor (PVT) serves as Alluci’s real-time thermodynamic health and stability engine. Operating as a continuous diagnostic monitor within the ExecutiveOrchestrator, PVT models the cognitive state space using a thermodynamic triple ($P, V, T$) and Frenet-Serret state trajectory kinematics. It measures manifold pressure, available agency volume, entropy temperature, and trajectory curvature to prevent system instability, topological drift, and unauthorized execution runaways.
trajectory.py)CRITICAL state.ExecutiveOrchestrator immediately engages an emergency safe-halt ($g=0$), freezing tool actions and locking execution to protect workspace state.manifold.pvt): Pushes live PVT telemetry triples ($P, V, T$) and curvature metrics over WebSocket RPC to client dashboards (PVTDashboard.tsx).pvt_json): Serializes PVT diagnostic state triples into SQLite audit log ledgers (pvt_json), generating an immutable record of system thermodynamic stability.The ACE aligns machine logic with human biology. It bridges raw data and human sentiment, ensuring the assistant works in resonance with your current physiological and mental state.
The Local Cognitive Engine (LCE) serves as Alluci’s native, on-device foundation intelligence substrate. Built around a Sovereign-First execution model, the LCE evaluates neural network models locally on host hardware—delivering ultra-low latency, zero-copy memory access, dynamic VRAM safeguards, and privacy-preserving cloud federation without cloud vendor lock-in or un-sanctioned data egress.
Official quantized model weights across all tiers are hosted on HuggingFace (Alluci LCE Models).
mlx_lm and mlx_vlm frameworks, leveraging Apple Silicon’s shared Unified Memory architecture for zero-copy tensor evaluation.asyncio.Lock inference semaphore, ensuring only one generation stream executes at any given moment to protect Metal GPU command buffers from memory panics.ThreadPoolExecutor), while multi-agent task queues manage async token dispatching in parallel.mlx_lm model classes at runtime without monkey-patching codebase files.local_bridge.py utilizing standard llama.cpp C++ GGUF bindings or CUDA-accelerated PyTorch/vLLM adapters.Automatically profiles available System RAM and VRAM upon initialization, mapping the host environment to Apple’s product lineup and optimal model precision tiers:
TIER_0_ULTRA ($\ge 128\text{ GB} - 512\text{ GB}$ Unified RAM / $\ge 96\text{ GB}$ Code Threshold): Flagship Workstations & Sovereign Server Nodes (MacBook Pro / Mac Studio / Mac Pro Ultra) running unquantized 31B 16-bit (BF16) dense models.TIER_1_MAX ($64\text{ GB} - 96\text{ GB}$ Unified RAM / $\ge 60\text{ GB}$ Code Threshold): High-Performance Studio & Pro Workstations (MacBook Pro / Mac Studio Max) running high-density 31B 8-bit / 4-bit models.TIER_2_PRO ($32\text{ GB} - 48\text{ GB}$ Unified RAM / $\ge 30\text{ GB}$ Code Threshold): Executive & Developer Laptops (MacBook Pro Pro/Max Series) running 26B Mixture-of-Experts (MoE) 4-bit models.TIER_3_BASE ($16\text{ GB} - 24\text{ GB}$ Unified RAM / $\ge 15\text{ GB}$ Code Threshold): Standard Consumer Hardware (MacBook Air, Mac mini, iMac) running 12B 4-bit dense models.TIER_4_EDGE ($8\text{ GB} - 12\text{ GB}$ Unified RAM / $< 15\text{ GB}$ Code Threshold): Mobile Devices & Sentinels (iPhone 17 Series / Base Macs) running lightweight 2B 4-bit models.mx.set_cache_limit) to prevent host system slowdowns._apply_streaming_attention_sink() permanently pins initial system directives, zero-trust invariants, and grounding laws at token 0 (sink size: 2,000 chars) while maintaining a rolling active conversational tail (14,000 chars). Intermediate conversational turns are archived into H-LSM L1 episodic memory, enabling infinite multi-turn sessions without memory spikes.mx.clear_cache() and Python garbage collection calls execute before, during, and after every generation stream.models/loras/agent_{id}_lora.safetensors) directly into the active MLX model on the fly without restarting the engine process or breaking skill manifests.<ACE_ATTUNEMENT_DIRECTIVE> into system prompts matching real-time Apple Watch biometrics (HRV, respiratory rate, stress score).mirror_cache/alluci-polytope-gemma-4-e2b-it-4bit) as an asynchronous speculator with the dense verifier model (mirror_cache/alluci-polytope-gemma-4-31b-it-bf16).mlx_lm.stream_generate(..., draft_model=draft_engine), achieving 2.5x–4x faster local inference speeds with zero loss in mathematical precision.AIRGAPPED, SENSITIVE, PUBLIC) and token complexity requirements.llama.cpp bindings or CUDA PyTorch/vLLM adapters) via local_bridge.py.ExecutiveRouter interface, decoupling the high-level Agent Harness (skills, tools, memory, bridges) from underlying model weights so base weights can be upgraded without breaking skill manifests.AIRGAPPED or SENSITIVE, hard-routing them 100% on-device inside the local MLX engine with zero network egress.AlluciSecureProxy. Sensitive names, phone numbers, email addresses, and private keys are extracted into a local ephemeral vault and replaced in the outbound prompt by abstract placeholders (e.g., <PERSON_1>, <PHONE_1>).AlluciSecureProxy restores the original vault data locally on your device, delivering complete answers without external cloud providers ever receiving raw user PII.The Local Voice & Conversational Speech Engine (AlluciVoiceOrchestrator in backend/inference/voice_orchestrator.py) provides native, zero-latency audio transcription and cross-device voice interaction. Operating natively on host hardware, the Voice Engine pairs Apple Silicon mlx_whisper speech-to-text with hybrid voice synthesis, dynamically routing audio payloads based on host device capabilities.
/ws/voice)backend/routers/voice.py).finalize_utterance) and dispatch text tokens to the LCE for reasoning.synthesize_response)WATCH_ULTRA & IPHONE_17_PRO): Delivers lightweight text tokens (type: "text_for_native_tts") to edge devices, triggering native Apple OS AVSpeechSynthesizer (Siri Voice Engine) on the Apple Watch and paired iPhone for battery-efficient, natural voice playback.MACBOOK_WORKSTATION): On developer workstations, synthesizes neural 24kHz PCM audio buffers using kokoro_mlx (kokoro_bridge.py), rendering studio-quality custom voice profiles directly on Metal GPU.TIER_MODEL_MAP)MACBOOK_WORKSTATION (Workstation Core): Runs unquantized whisper-large-v3-turbo for high-precision transcription coupled directly to local 31B foundation models.IPHONE_17_PRO (Mobile Hub): Runs 8-bit whisper-base-8bit alongside lightweight edge models (EDGE_2B_4BIT) for offline mobile speech recognition.WATCH_ULTRA (Edge Sentinel): Uses native WatchOS audio capture (AVAudioEngine) and native speech synthesis (AVSpeechSynthesizer), delegating all cognitive reasoning and heavy transcription to the paired iPhone or host workstation over encrypted P2P WebSocket tunnels.The Executive Orchestrator serves as Alluci’s high-level planning and task execution engine. It transforms complex, ambiguous user objectives into structured, non-blocking execution pipelines. By combining hierarchical task decomposition, recurring background cron scheduling, real-time context compression, and continuous statistical safety calibration, the Orchestrator manages multi-agent Constellations with sub-second execution efficiency.
task_deadline, file_watch, goal_progress, url_fetch, system_health, bridge_silence, subagent_loop, topological_drift).barcode_clock.tick() ($N \to N+1$).JSpaceSimulator during low-load windows ($22:00–07:00$), persisting verified recovery triplets to DPOTripletHarvester.SupervisorAgent condenses verbose worker node outputs into dense "Sovereign Context Tokens" before passing state to downstream nodes in the DAG, preventing context-window bloat and maximizing token efficiency.AIRGAPPED, SENSITIVE, PUBLIC), model strengths, and execution speed—dispatching private data locally to the LCE engine while routing high-density web synthesis to fast cloud APIs.Alluci is built from the ground up as a Self-Sovereign Multi-Agent Operating System. Rather than executing all workloads within a single monolithic prompt loop, Alluci allows you to instantiate, configure, and orchestrate arrays of specialized agents (AgentRecord) operating as autonomous background daemons, channel handlers, or parallel DAG worker nodes.
AgentRecord)Each agent in the Constellation is backed by a stateful AgentRecord table in SQLite, defining its identity, underlying foundation model, and operational parameters:
alluci-polytope4-31b) to cloud foundation models (OpenAI gpt-4o, Anthropic claude-3-5-sonnet, Google gemini-1.5-pro).fallback_chain): Configures ordered model failover routes (e.g., gpt-4o -> claude-3-5-sonnet -> local_mlx), guaranteeing execution continuity if primary cloud endpoints experience outages or rate limits.engine_manifest): Fine-tunes cognitive execution parameters per agent, including Thinking Depth (thinking_level), Verbose Output Scales (verbose_level), and Multi-Step Reasoning Intensity (reasoning_level).To prevent cross-domain context contamination, sub-agents are provisioned with granular access controls across seven dedicated configuration tabs (AgentDetailTabs.tsx):
skills_manifest): Grants or restricts domain-specific skill manifests (e.g. Legal Contract Audit, Compensation Strategy, Deep Research, SFT LoRA Forge).tools_manifest): Enforces fine-grained permissioning over available executable tools (Shell Executor, Memory Adapter, Web Browser, Vault Keys), ensuring sub-agents operate strictly within authorized boundaries.soul_profile_id / soul_manifest_override): Allows sub-agents to inherit or override the system's global Soul Manifest with specialized domain personas.HeartbeatOrderRecord): Schedules periodic diagnostic probes (fired_at, probe_type, action_type) to execute background health sweeps, channel monitoring, or memory maintenance automatically.ExecutiveOrchestrator parses complex, ambiguous user goals into Directed Acyclic Graphs (DAGs). Sub-tasks are dispatched in parallel across specialized sub-agents running concurrently.SupervisorAgent condenses verbose worker node outputs into dense Sovereign Context Tokens before propagating state to downstream DAG nodes.pii_override_enabled): Allows administrative override or enforcement of inline PII pseudonymization for specific sub-agents handling sensitive data streams through the AlluciSecureProxy.The Hierarchical Long-Short Manifold (H-LSM) is Alluci’s 4‑tier stateful memory architecture. Managed by HLSMManager (backend/memory/hlsm_manager.py) augmented by the Markov Trace & Spectral Geometry Engine (backend/memory/markov_trace.py).
H-LSM enables the agent to retain personal and organizational memory over time without context‑window bloat, context degradation, or hallucinations.
H-LSM operates across four cognitive memory storage tiers:
• L0 Working Memory: Ultra‑fast, session‑level expiring context backed by Redis (Key‑Value) with automatic zero-config fallback to SQLite table hlsm_working.
• L1 Episodic Memory: Full chat turns, interaction history, and episodic event logs backed by SQLite table hlsm_episodic with a high‑performance SQLite FTS5 full‑text search index (hlsm_episodic_fts).
• L2 Semantic Memory: Long‑term vector embeddings for retrieval‑augmented generation (RAG), backed by Sentence‑Transformers (all‑MiniLM‑L6‑v2) and KùzuDB graph nodes (polytope_data.kuzu).
• L3 Knowledge Graph: Permanent structured entity‑relationship graph nodes backed by the KùzuDB embedded graph database engine (polytope_data.kuzu).
Tri-Hybrid Reciprocal Rank Fusion (RRF $k=60$):
• Parallel Asynchronous Retrieval: Dispatches queries concurrently across L1 SQLite FTS5 ($w=1.0$), L2 MiniLM Dense Vectors ($w=1.2$), and L3 KùzuDB Knowledge Graph Entities ($w=1.4$).
• Authoritative Score Fusion: Harmonizes multi-modal score distributions using the standard RRF constant ($k=60$):
$$\text{Score}{\text{RRF}}(d) = \sum{t \in {\text{L1}, \text{L2}, \text{L3}}} \frac{w_t}{60 + \text{rank}_t(d)}$$
• Knowledge Graph Entity Injection: Automatically extracts retrieved entity relations from KùzuDB and injects them directly into prompt grounding contexts under structured entity headers (── Knowledge Graph Entities ──).
Markov Trace Multi-Hop Rescoring & Scale-Dependent Spectral Geometry (markov_trace.py):
• Schur Complement Trace Operator: Uncovers multi-hop hidden excursion pathways across visible and hidden memory nodes:
$$\text{Tr}_A(P) = A + B(I - C + \epsilon I)^{-1} D$$
boosting visible candidate scores (80% direct semantic relevance + 20% topological excursion boost) and promoting high-coupling hidden bridge nodes.
• Symmetrized Normalized Laplacian ($L_A$): Computes normalized Laplacian eigenvalues $\lambda_i \ge 0$, Fiedler algebraic connectivity ($\lambda_2$), and heat return probability $P_A(\sigma) = \frac{1}{|A|} \sum e^{-\sigma \lambda_i}$.
• Dynamic Context Depth Scaling: Derives the scale-dependent spectral dimension $d_s^A(\sigma) = 2\sigma \frac{\sum \lambda_i e^{-\sigma \lambda_i}}{\sum e^{-\sigma \lambda_i}}$, dynamically expanding retrieval depth (max_per_tier) when mixing is sparse ($d_s^A > 1.5$).
Alluci utilizes a specialized "Training Sandbox" mode that leverages the Unsloth library (optimized for 80% less VRAM usage) to perform Supervised Fine‑Tuning (SFT) directly on your hardware.
When the system detects low cognitive load (you are asleep or away), the daemon halts external polling and reallocates 100% of hardware resources to internal evolution:
j_space_simulator.py) simulating boundary recovery, 3) Teacher Synthesis (air-gapped local 31B Dense model instruction pair synthesis), 4) Cognitive Distillation (Socratic questioning of episodic logs into permanent Semantic Truths), and 5) Preference Harvesting.dpo_harvester.py, markov_trace.py): Automatically harvests teacher-student preference triplets $(x, y_w, y_l)$ from:
failed_plan $\to$ successful_plan).reverted_code $\to$ repaired_code).The Soul Manifest serves as Alluci’s core behavioral blueprint and active cognitive runtime engine. Moving beyond static system prompts and plain .md files, Alluci decouples persona configuration into a stateful, auditable Soul Manifest that actively drives model sampling parameters, dynamic neural-weight adapters, zero-trust security gates, and bio-affective attunement loops in real time.
apply_lora_adapter): Rather than cluttering context windows with lengthy text instructions, Soul Profiles hot-swap compiled LoRA neural weights (agent_{id}_lora.safetensors) directly into VRAM on the fly without restarting the inference engine process.contentmultimap) for portable identity, with local AES-256-GCM envelope encryption for air-gapped sovereignty.identityCore), voice profiles (voiceProfile), system directives, and boot sequence parameters (bootSequence).SoulPreferences).active_skill_ids) and executable tool IDs (active_tool_ids) directly to the soul context, restricting or expanding agency based on active persona.SoulProfileRecord): Supports creating, updating, listing, and switching between pre-configured Soul Profiles stored in the local SQLite database (/soul/profiles), allowing users to toggle between executive, technical, creative, or analytical personas on the fly./soul/preview): Features a dedicated preview endpoint that executes candidate prompts through the current Soul Manifest before committing updates to active agent sessions, providing instant feedback on persona alignment and safety constraints.Traditional AI agent frameworks define "Skills" and "Tools" as static markdown text files (SKILL.md) or simple string descriptions embedded in system prompts. This legacy approach suffers from severe limitations: high context window bloat, steep API token costs, floating-point non-determinism, soft pattern-matching hallucinations, and a complete lack of runtime execution validation.
The Alluci Sovereign Agent completely re-architects Skills and Tools from passive text documents into Active Cognitive Python Runtimes and Skill-Specific Deterministic Tool Engines. Managed by the SkillManager (backend/routers/skills.py) and ToolRegistry (backend/routers/tools.py), Skills and Tools operate as compiled, stateful runtimes driven by five deterministic cognitive parameters (Knowledge, Mindsets, Methodologies, Chains of Thought, and Logic), zero-trust security gates, and hardware biometric governance.
When creating or instantiating a Skill, the Skill Builder Engine configures five deterministic parameters that govern the active Python Skill Runtime:
L3 Knowledge Graph), semantic embeddings (L2 Vector RAG), and indexed interaction history (L1 Episodic FTS5) without factual drift.SEC-005 int16 clamping) and discrete integer simplicial boundary operators ($\partial_k: C_k \to C_{k-1}$), eliminating floating-point non-determinism across Host CPU, CUDA GPU, and Apple Metal GPU runtimes.LoRAForge (backend/engine/lora_forge.py) crystallizes these trajectories into native PyTorch/MLX LoRA adapters (e.g., coding_lora.safetensors, legal_lora.safetensors).apply_lora_adapter(), delivering domain expertise with zero prompt-window bloat.AntNetworkProtocol): Skill execution paths are mapped into Betti topological barcodes ($\beta_0, \beta_1, \beta_2$) and broadcast over the Verus P2P network, allowing multi-agent constellations to share skill intelligence zero-knowledge across devices.Tools in Alluci are Skill-Specific Deterministic Tool Engines backed by sandboxed Python runtimes, Model Context Protocol (MCP) servers, JSON-RPC daemons, and compiled C++ kernels:
alluci_vault/tools/ and core_tools/) with explicit JSON Schema contracts, rate limits, and timeout boundaries.WebSearchAdapter): Decomposes complex research queries into parallel orthogonal search vectors executed concurrently with strict 4.0s timeouts, URL deduplication, and a dedicated 24-hour TTL SQLite cache (ResearchDossierCache in backend/data/research_cache.db), serving repeat lookups with 0ms latency and real markdown citations.Alluci implements a zero-trust, hardware-anchored security model that couples system execution directly to physical human presence and device liveness. Rather than relying solely on software passwords or API key tokens, Alluci enforces multi-modal biometric liveness, hardware kill switches, interactive executive governance, and isolated cryptographic vault containers to guarantee absolute data sovereignty and prevent unauthorized execution.
backend/routers/gemini.py).SecurityInterventionModal.tsx), requiring explicit administrative authorization ([ Approve & Execute Action ]) before operations proceed.BioTelemetryAuth / PPN-017)BioTelemetryAuth.is_on_wrist=True) and active heart rate pulse before executing sensitive operations (banking, db_write, file_overwrite, os_exec, crypto_tx).REQUIRE_WATCH_TELEMETRY=True), loss of wrist contact or missing pulse instantly activates the Sovereign Kill Switch—aborting execution, locking the agent, and encrypting active working memory.PPN-018)Alluci is built natively around the Verus DREAM (Decentralized Real-time Encrypted Application Model) framework. By abandoning centralized cloud application servers, API keys, and third-party database proxies, Alluci pairs local-first machine intelligence with VerusID self-sovereign identities, structured VDXF data namespaces, local blockchain nodes, and encrypted peer-to-peer (P2P) state synchronization.
identity@).verus_rpc.py)verus_get_info, verus_get_identity).verus_send_currency), and creates decentralized marketplace orders (verus_make_offer) natively on-device.vdxf_store.py)verus_get_vdxf_id) to structure application data, skill manifests, and agent configurations without vendor lock-in.contentmultimap): Stores and retrieves encrypted agent manifests and peer messages directly on the VerusID content multimap (VDXFStore), creating a portable, decentralized state storage layer.audit_ledger.py / verus_txid)AuditLedger and H-LSM memory manifolds.verus_txid): Anchors state integrity hashes and executive action summaries directly to the Verus blockchain (verus_txid and vdxf_key), generating an un-alterable, mathematically verifiable audit log of agent history.AntNetworkProtocol)AntNetworkProtocol (Alluci_Ant_v1) over Verus VDXF messaging channels to coordinate multi-agent constellations across distributed devices.For enterprise environments requiring strict GDPR or Schrems II compliance, the Sovereign Agent utilizes a "Defense in Depth" proxy strategy:
DATA_REGION="EU" in the environment mathematically prevents any cloud egress without passing through the pseudonymization proxy.ENFORCE_EU_ENDPOINTS=True forces Azure OpenAI and Google Vertex API clients to dynamically route to EU-based datacenters on the fly.[!NOTE] See the full Data Residency & Compliance Architecture for legal and technical implementation details.
Alluci includes an integrated Usage & Cost Analytics Engine (UsageTracker in backend/analytics.py and backend/routers/usage.py) that delivers real-time token tracking, financial telemetry, multi-provider model cost rollups, and spending optimization across all cloud and local execution paths.
/usage)/usage/summary), daily usage rollups (/usage/daily), and turn-by-turn cumulative session curves (/usage/sessions/{session_key}/timeseries)./usage/sessions): Provides session-level audit metrics detailing agent identities, provider distributions, model selection, total turn counts, and timestamp logs.AIRGAPPED, SENSITIVE, PUBLIC)./usage/sessions/export/csv)The Sovereignty Level Wizard makes onboarding seamless. Choose between Cloud-only (Level 1), Local Edge (Level 2), or the Full Sovereign Base (Level 3).
Before installing Alluci, verify that your host environment meets the following requirements:
npm (v10+)pipclang++ on macOS, g++ on Linux, MSVC on Windows), make, git, and lsof (Required to compile native DPK security kernels)mlx, mlx-lm, mlx-vlm, mlx-whisper) leveraging Unified Memorytorch>=2.4.0), sentence-transformers, or llama.cpp GGUF bindings via local_bridge.pyhuggingface_hub CLI for downloading model weights from HuggingFace (Alluci Models)kuzu embedded C++ engine) powering H-LSM Knowledge Graphv7.0+, optional for high-speed L0 Working Memory; automatically falls back to SQLite in zero-config LITE_MODE)verusd node RPC daemon for VerusID decentralized identity, VDXF content maps, and on-chain audit ledger anchoringbridges/iwatch.py) or wearable webhooks (Garmin, Whoop, Oura) for bio-affective stress attunement and the Sovereign Kill SwitchAlluci features an automated, hardware-aware model downloader (scripts/download_models.py).
Hardware-Aware Model Provisioning (Online Setup):
Running ./scripts/setup_sovereign_stack.sh triggers HardwareProfiler.get_system_profile(). The profiler scans host System RAM, VRAM, and GPU architecture, automatically downloading the optimal model weights directly from HuggingFace (Alluci Models) into your local mirror_cache/:
TIER_0_ULTRA through TIER_4_EDGE).EDGE_2B_4BIT) for draft-verification token acceleration.all-MiniLM-L6-v2) for local RAG vector search.Air-Gap Activation (100% Offline Sovereignty):
Once the setup script outputs [ INFO ]: Setup Complete, all model weights, tokenizer manifests, and embedding models are cached locally. You can physically disconnect network cables or disable Wi-Fi, and the Sovereign Agent will execute indefinitely offline with zero external network dependencies.
Automated Stack Initialization
chmod +x scripts/setup_sovereign_stack.sh
./scripts/setup_sovereign_stack.sh
Managing the Stack via Makefile The easiest way to run the entire stack locally is using our pre-configured Makefile:
make init # Initialize .env, virtualenv, and install dependencies via bootstrap_all.sh
make start # Cleanly start Backend (Port 8000) and Frontend (Port 3000)
make status # Verify port 8000/3000 status and active services
make doctor # Run diagnostic check on toolchain and local environment (scripts/verify_local.py)
make stop # Gracefully terminate active background processes
Manual Startup Alternative:
source .venv/bin/activate && uvicorn backend.app:app --port 8000 --host 0.0.0.0npm run dev -- --port 3000 --host 0.0.0.0Open http://localhost:3000 to launch the Alluci Sovereign Gateway. Upon first launch, the Sovereignty Wizard will guide your configuration.
The Sovereign Agent uses a strictly local .env file to seed its Verus Vault and configuration parameters:
cp .env.example .env
Configure core environment keys in .env:
POLYTOPE_MASTER_KEY: Master seed for AES-256 vault encryption and 2FA secrets.JWT_SECRET_KEY: Used for secure session token signing.VERUS_ID_IDENTITY: Sovereign VerusID identity handle (YourIdentity@).VERUS_ID_PRIVATE_KEY: Ed25519 private key seed for executive manifest signing.REQUIRE_WATCH_TELEMETRY: Set to True to enforce biometric kill switch liveness checks.DATA_REGION: Set to EU to enforce the SecureProxy PII firewall.ENFORCE_EU_ENDPOINTS: Set to True for strict physical EU cloud datacenter routing.Alluci incorporates a rigorous quality gate to guarantee local system stability, zero-trust security, and immutable supply-chain integrity:
make quality
The Quality Gate Executes:
scripts/production_readiness/preflight.sh).pytest backend/tests/ -v) and performance benchmarks (pytest backend/tests/performance/test_benchmarks.py).npm audit, pip-audit, and static secret detection scanning.reports/ (generate_release_report.py).To run tests manually:
source .venv/bin/activate
pytest backend/tests/ -v
The DEBUG environment variable controls system diagnostic verbosity:
DEBUG=False): Mutes internal exception tracebacks, masks FastAPI error details, and sanitizes JSON-RPC response payloads.DEBUG=True): Enables full exception tracebacks, detailed validation data, and verbose topological log output.Set DEBUG=True in your .env or export the variable locally to enable detailed diagnostics during development.
Copyright © 2026 Alluci-Ai. All Rights Reserved.
This software and associated documentation files (the "Software") are the proprietary property of Alluci-Ai. Unauthorized copying, reproduction, distribution, modification, or use of this Software, via any medium, is strictly prohibited without the express written permission of Alluci-Ai.
For information on our strictly-gated proprietary contribution process, please review our Contribution Guidelines.
"Alluci-Polytope: Turning AI from a passive tool into a sovereign, affective partner."
The Self-Sovereign Personal/Professional AI Assistant
The Alluci Sovereign Agent is a self-sovereign, multi-agent computational runtime that serves as your primary personal and professional interface acting as your high-level digital assistant, orchestrating complex workflows, multi-step research, and multi-channel communications.
Alluci unifies local on-device intelligence with policy-driven cloud model federation—allowing you to harness frontier AI capabilities while your data, memories, workflows, and intellectual property remain cryptographically secured and physically under your control within a single Self-Sovereign Agentic Operating System.
The Sovereign Manifold acts as your central neural dispatch for all digital communications, workflows, and biometric state tracking. Rather than forcing you to jump between fragmented apps and isolated browser tabs, Alluci unifies your entire digital life under a single sovereign interface.
Every channel integration operates inside an isolated cryptographic Simplicial Vault bound to your VerusID, ensuring seamless multi-channel agency without cross-channel data leaks or unauthorized exposure across four core operational manifolds:
The Multi-Modal Synthesis & API Orchestration engine serves as Alluci’s unified control plane for generative tools, token routers, and cognitive services. Rather than locking you into a single closed ecosystem, Alluci provides policy-driven model federation—dynamically routing tasks across specialized foundation models, voice synthesis engines, and generative media tools while respecting your local privacy constraints and token budge.
The Polytope Manifold Architecture serves as the core cognitive blueprint governing how Alluci processes intelligence, preserves stateful memory, and executes multi-agent workflows.
Alluci is powered by a hybrid computational runtime—combining native Python execution engines with high-performance compiled C++ extensions and specialized topological kernels. This architecture pairs proactive cognition and a native Apple MLX engine driving on-device foundation model evaluation on Unified Memory with Non-Euclidean geometric manifold mapping and Betti signature context indexing across a stateful 4-Tier Memory System.
System execution is governed by a three-pillar action safety loop enforcing Lipschitz gradient smoothness and payload verification, integer simplicial boundary operators for Betti topology discrete manifold verification, high-frequency signal processing and harmonic lattice calculations, and cryptographic Simplicial Vault isolation encrypting credentials and bridge secrets via AES-256-GCM.
The Polytope Projection Network (PPN) serves as Alluci’s non-Euclidean geometric intelligence engine. Moving beyond traditional, hallucination-prone vector similarity lookups, PPN projects unstructured multi-modal data streams—text, biometrics, tool actions, and execution traces—into topologically stable geometric manifolds. Governed by algebraic topology and simplicial homology, PPN evaluates state continuity using Betti signatures ($\beta_0, \beta_1, \beta_2$), ensuring that cognitive operations maintain structural integrity across execution cycles.
SEC-005)ACE)_perform_ppn_check): Evaluates candidate task objectives and tool actions for topological tearing ($\Delta \beta$ norm spikes, entropy threshold breaches) before committing steps to execution pipelines.Structural Barcode Extraction: Distills complex problem-solving paths into compact, invariant topological barcodes.
Zero-Knowledge Swarm Broadcast: Broadcasts structural barcodes over the Verus P2P network, enabling federated multi-agent swarm intelligence without exposing raw prompt context or private user data.
The Discrete Projection Kernel (DPK) serves as the high-speed, zero-trust cryptographic gatekeeper of the Alluci execution runtime. Grounded in Kepler's Stella Octangula $S_8$ geometry (compound of dual regular tetrahedra $T_+ \cup T_-$ with 8 vertices, 12 edges, 8 faces, and central octahedron $O_6$), DPK validates state transition vectors ($\mathbf{x}_{t-1} \to \mathbf{x}_t$), enforcing topological boundary nilpotence, Euler characteristic invariants ($\chi = V - E + F$), and idempotent fusion projections before any tool or agent action executes.
dpk_kernel.cpp / ctypes), falling back to a pure Python implementation when hardware constraints dictate.TearingException, instantly halting execution to prevent state corruption or hallucinated loop cascades.AAP-003)PolytopeState.CalibrationManager to dynamically calibrate safety rejection thresholds based on execution history, affective tension ($\psi$), and active workspace permissions.is_override=True), allowing authorized users to bypass false-positive manifold halts while preserving audit logs.The Sovereign Topological State Space Subsystem (backend/topology/) formalizes Alluci's cognitive reasoning into a mathematically bounded 5-tuple $(W, X, \mathcal{J}, G, N)$ governed by rigorous algebraic topology operators:
┌────────────────────────────────────────────────────────┐
│ W (World Data Space) │
└──────────────────────────┬─────────────────────────────┘
│ P: W × X → [0,1]
▼ (Vietoris-Rips Filtration)
┌────────────────────────────────────────────────────────┐
│ X (Experience Simplicial Space) │
│ [Betti Invariants: β₀, β₁, β₂, β₃] │
└──────────────────────────┬─────────────────────────────┘
│ S: X × G × J → J
▼ (Simplicial CoT & Socratic Synthesis)
┌────────────────────────────────────────────────────────┐
│ J (J-Space Counterfactual Simulation Sandbox) │
│ Kepler S₈ Synthesis: T₊ ∪ T₋ → O₆ Kernel │
└──────────────────────────┬─────────────────────────────┘
│ D: J × G → [0,1]
▼ (Convex Hull Affordance)
┌────────────────────────────────────────────────────────┐
│ G (Action Affordance Envelope Space) │
│ [3D Risk Simplex & Sub-Agent Bounds] │
└──────────────────────────┬─────────────────────────────┘
│ A: G × W → [0,1]
▼ (Markov Trace & DPO Harvesting)
┌────────────────────────────────────────────────────────┐
│ N (Discrete Topological Barcode Clock Count) │
│ [Monotonic Pacing: N → N+1, Birth/Death Tracking] │
└────────────────────────────────────────────────────────┘
PMETFiltrationEngine): Samples multi-dimensional point clouds from $W$, constructs Vietoris-Rips complexes up to 2-skeleton (triangular faces), and extracts exact Betti invariants ($\beta_0$ connected components, $\beta_1$ 1-skeleton cycles, $\beta_2$ 2-voids).JSpaceSimulator): Evaluates multi-step counterfactual simulation traces, validating deductive reasoning steps as 2-simplices to ensure algebraic boundary nilpotence ($\partial_1 \circ \partial_2 = 0$). Reconciles constructive hypotheses ($T_+$) and critical skeptic critiques ($T_-$) into the central intersection kernel ($O_6$).ActionAffordanceEnvelope): Validates candidate execution vectors against sub-agent domain boundaries (Codi, Rocco, Admin) and bio-affective stress thresholds ($\psi \le 0.85$), ensuring destructive tasks are strictly intercepted by HITL governance.MarkovTraceEngine & DPOTripletHarvester): Executes verified actions, evaluates multi-step trajectories using the Schur complement Markov Trace operator ($\text{Tr}_A(P) = A + B(I-C)^{-1}D$), monitors Frenet-Serret curvature ($\kappa \le 5.0$), and records verified $(x, y_w, y_l)$ preference triplets for offline distillation.TopologicalBarcodeClock)The Action Verification Loop (AVL Gate) serves as Alluci’s zero-trust safety and payload verification engine. Functioning as an inline firewall between LLM generation outputs and tool execution adapters, the AVL Gate enforces a mathematical three-pillar security protocol. It prevents unauthorized code execution, prompt injections, and structural hallucinations by verifying cryptographic attribution, gradient smoothness limits, and topological continuity before any action payload is committed.
project_to_boundary): Projects near-boundary prompt violations back into admissible Lipschitz bounds, neutralizing prompt injection attacks without disrupting execution flow.verify_action_payload): Dynamically scales and clamps numeric tool parameters (top_k, limit, timeout, depth, steps, count, max_tokens) proportionally to available Lipschitz budget capacity.ExecutiveOrchestrator self-healing loop injects a high-priority <SECURITY_RUPTURE> prompt directive, instructing the agent to regenerate a safe, strictly bounded plan.HUMAN-IN-THE-LOOP REQUIRED mode, halting autonomous execution to preserve workspace integrity.CalibrationManager (avl_calibration_cache.json) to continuously track execution history, tool success rates, and affective tension ($\psi$).The Proactive Cognition Layer (PCL) serves as Alluci’s continuous background reasoning and autonomous intelligence engine. Architecturally distinct from passive event watchers or simple cron pollers, PCL operates as an autonomous cognitive loop—continuously observing system signals, constructing stateful world models, identifying execution opportunities, and executing proactive workstreams without requiring explicit user prompting.
OBSERVE → MODEL → DETECT → JUDGE → ACT)WorldModel snapshot persisted to SQLite database tables (pcl_world_snapshot).StalledGoalDetector, UnresolvedThreadDetector, HardwareAnomalyDetector, AffectiveStressDetector) to discover actionable tasks.ExecutiveOrchestrator or broadcasts non-intrusive administrative notifications via streaming WebSockets (JsonRpcGateway).ACE Integration)The PVT Manifold Health Monitor (PVT) serves as Alluci’s real-time thermodynamic health and stability engine. Operating as a continuous diagnostic monitor within the ExecutiveOrchestrator, PVT models the cognitive state space using a thermodynamic triple ($P, V, T$) and Frenet-Serret state trajectory kinematics. It measures manifold pressure, available agency volume, entropy temperature, and trajectory curvature to prevent system instability, topological drift, and unauthorized execution runaways.
trajectory.py)CRITICAL state.ExecutiveOrchestrator immediately engages an emergency safe-halt ($g=0$), freezing tool actions and locking execution to protect workspace state.manifold.pvt): Pushes live PVT telemetry triples ($P, V, T$) and curvature metrics over WebSocket RPC to client dashboards (PVTDashboard.tsx).pvt_json): Serializes PVT diagnostic state triples into SQLite audit log ledgers (pvt_json), generating an immutable record of system thermodynamic stability.The ACE aligns machine logic with human biology. It bridges raw data and human sentiment, ensuring the assistant works in resonance with your current physiological and mental state.
The Local Cognitive Engine (LCE) serves as Alluci’s native, on-device foundation intelligence substrate. Built around a Sovereign-First execution model, the LCE evaluates neural network models locally on host hardware—delivering ultra-low latency, zero-copy memory access, dynamic VRAM safeguards, and privacy-preserving cloud federation without cloud vendor lock-in or un-sanctioned data egress.
Official quantized model weights across all tiers are hosted on HuggingFace (Alluci LCE Models).
mlx_lm and mlx_vlm frameworks, leveraging Apple Silicon’s shared Unified Memory architecture for zero-copy tensor evaluation.asyncio.Lock inference semaphore, ensuring only one generation stream executes at any given moment to protect Metal GPU command buffers from memory panics.ThreadPoolExecutor), while multi-agent task queues manage async token dispatching in parallel.mlx_lm model classes at runtime without monkey-patching codebase files.local_bridge.py utilizing standard llama.cpp C++ GGUF bindings or CUDA-accelerated PyTorch/vLLM adapters.Automatically profiles available System RAM and VRAM upon initialization, mapping the host environment to Apple’s product lineup and optimal model precision tiers:
TIER_0_ULTRA ($\ge 128\text{ GB} - 512\text{ GB}$ Unified RAM / $\ge 96\text{ GB}$ Code Threshold): Flagship Workstations & Sovereign Server Nodes (MacBook Pro / Mac Studio / Mac Pro Ultra) running unquantized 31B 16-bit (BF16) dense models.TIER_1_MAX ($64\text{ GB} - 96\text{ GB}$ Unified RAM / $\ge 60\text{ GB}$ Code Threshold): High-Performance Studio & Pro Workstations (MacBook Pro / Mac Studio Max) running high-density 31B 8-bit / 4-bit models.TIER_2_PRO ($32\text{ GB} - 48\text{ GB}$ Unified RAM / $\ge 30\text{ GB}$ Code Threshold): Executive & Developer Laptops (MacBook Pro Pro/Max Series) running 26B Mixture-of-Experts (MoE) 4-bit models.TIER_3_BASE ($16\text{ GB} - 24\text{ GB}$ Unified RAM / $\ge 15\text{ GB}$ Code Threshold): Standard Consumer Hardware (MacBook Air, Mac mini, iMac) running 12B 4-bit dense models.TIER_4_EDGE ($8\text{ GB} - 12\text{ GB}$ Unified RAM / $< 15\text{ GB}$ Code Threshold): Mobile Devices & Sentinels (iPhone 17 Series / Base Macs) running lightweight 2B 4-bit models.mx.set_cache_limit) to prevent host system slowdowns._apply_streaming_attention_sink() permanently pins initial system directives, zero-trust invariants, and grounding laws at token 0 (sink size: 2,000 chars) while maintaining a rolling active conversational tail (14,000 chars). Intermediate conversational turns are archived into H-LSM L1 episodic memory, enabling infinite multi-turn sessions without memory spikes.mx.clear_cache() and Python garbage collection calls execute before, during, and after every generation stream.models/loras/agent_{id}_lora.safetensors) directly into the active MLX model on the fly without restarting the engine process or breaking skill manifests.<ACE_ATTUNEMENT_DIRECTIVE> into system prompts matching real-time Apple Watch biometrics (HRV, respiratory rate, stress score).mirror_cache/alluci-polytope-gemma-4-e2b-it-4bit) as an asynchronous speculator with the dense verifier model (mirror_cache/alluci-polytope-gemma-4-31b-it-bf16).mlx_lm.stream_generate(..., draft_model=draft_engine), achieving 2.5x–4x faster local inference speeds with zero loss in mathematical precision.AIRGAPPED, SENSITIVE, PUBLIC) and token complexity requirements.llama.cpp bindings or CUDA PyTorch/vLLM adapters) via local_bridge.py.ExecutiveRouter interface, decoupling the high-level Agent Harness (skills, tools, memory, bridges) from underlying model weights so base weights can be upgraded without breaking skill manifests.AIRGAPPED or SENSITIVE, hard-routing them 100% on-device inside the local MLX engine with zero network egress.AlluciSecureProxy. Sensitive names, phone numbers, email addresses, and private keys are extracted into a local ephemeral vault and replaced in the outbound prompt by abstract placeholders (e.g., <PERSON_1>, <PHONE_1>).AlluciSecureProxy restores the original vault data locally on your device, delivering complete answers without external cloud providers ever receiving raw user PII.The Local Voice & Conversational Speech Engine (AlluciVoiceOrchestrator in backend/inference/voice_orchestrator.py) provides native, zero-latency audio transcription and cross-device voice interaction. Operating natively on host hardware, the Voice Engine pairs Apple Silicon mlx_whisper speech-to-text with hybrid voice synthesis, dynamically routing audio payloads based on host device capabilities.
/ws/voice)backend/routers/voice.py).finalize_utterance) and dispatch text tokens to the LCE for reasoning.synthesize_response)WATCH_ULTRA & IPHONE_17_PRO): Delivers lightweight text tokens (type: "text_for_native_tts") to edge devices, triggering native Apple OS AVSpeechSynthesizer (Siri Voice Engine) on the Apple Watch and paired iPhone for battery-efficient, natural voice playback.MACBOOK_WORKSTATION): On developer workstations, synthesizes neural 24kHz PCM audio buffers using kokoro_mlx (kokoro_bridge.py), rendering studio-quality custom voice profiles directly on Metal GPU.TIER_MODEL_MAP)MACBOOK_WORKSTATION (Workstation Core): Runs unquantized whisper-large-v3-turbo for high-precision transcription coupled directly to local 31B foundation models.IPHONE_17_PRO (Mobile Hub): Runs 8-bit whisper-base-8bit alongside lightweight edge models (EDGE_2B_4BIT) for offline mobile speech recognition.WATCH_ULTRA (Edge Sentinel): Uses native WatchOS audio capture (AVAudioEngine) and native speech synthesis (AVSpeechSynthesizer), delegating all cognitive reasoning and heavy transcription to the paired iPhone or host workstation over encrypted P2P WebSocket tunnels.The Executive Orchestrator serves as Alluci’s high-level planning and task execution engine. It transforms complex, ambiguous user objectives into structured, non-blocking execution pipelines. By combining hierarchical task decomposition, recurring background cron scheduling, real-time context compression, and continuous statistical safety calibration, the Orchestrator manages multi-agent Constellations with sub-second execution efficiency.
task_deadline, file_watch, goal_progress, url_fetch, system_health, bridge_silence, subagent_loop, topological_drift).barcode_clock.tick() ($N \to N+1$).JSpaceSimulator during low-load windows ($22:00–07:00$), persisting verified recovery triplets to DPOTripletHarvester.SupervisorAgent condenses verbose worker node outputs into dense "Sovereign Context Tokens" before passing state to downstream nodes in the DAG, preventing context-window bloat and maximizing token efficiency.AIRGAPPED, SENSITIVE, PUBLIC), model strengths, and execution speed—dispatching private data locally to the LCE engine while routing high-density web synthesis to fast cloud APIs.Alluci is built from the ground up as a Self-Sovereign Multi-Agent Operating System. Rather than executing all workloads within a single monolithic prompt loop, Alluci allows you to instantiate, configure, and orchestrate arrays of specialized agents (AgentRecord) operating as autonomous background daemons, channel handlers, or parallel DAG worker nodes.
AgentRecord)Each agent in the Constellation is backed by a stateful AgentRecord table in SQLite, defining its identity, underlying foundation model, and operational parameters:
alluci-polytope4-31b) to cloud foundation models (OpenAI gpt-4o, Anthropic claude-3-5-sonnet, Google gemini-1.5-pro).fallback_chain): Configures ordered model failover routes (e.g., gpt-4o -> claude-3-5-sonnet -> local_mlx), guaranteeing execution continuity if primary cloud endpoints experience outages or rate limits.engine_manifest): Fine-tunes cognitive execution parameters per agent, including Thinking Depth (thinking_level), Verbose Output Scales (verbose_level), and Multi-Step Reasoning Intensity (reasoning_level).To prevent cross-domain context contamination, sub-agents are provisioned with granular access controls across seven dedicated configuration tabs (AgentDetailTabs.tsx):
skills_manifest): Grants or restricts domain-specific skill manifests (e.g. Legal Contract Audit, Compensation Strategy, Deep Research, SFT LoRA Forge).tools_manifest): Enforces fine-grained permissioning over available executable tools (Shell Executor, Memory Adapter, Web Browser, Vault Keys), ensuring sub-agents operate strictly within authorized boundaries.soul_profile_id / soul_manifest_override): Allows sub-agents to inherit or override the system's global Soul Manifest with specialized domain personas.HeartbeatOrderRecord): Schedules periodic diagnostic probes (fired_at, probe_type, action_type) to execute background health sweeps, channel monitoring, or memory maintenance automatically.ExecutiveOrchestrator parses complex, ambiguous user goals into Directed Acyclic Graphs (DAGs). Sub-tasks are dispatched in parallel across specialized sub-agents running concurrently.SupervisorAgent condenses verbose worker node outputs into dense Sovereign Context Tokens before propagating state to downstream DAG nodes.pii_override_enabled): Allows administrative override or enforcement of inline PII pseudonymization for specific sub-agents handling sensitive data streams through the AlluciSecureProxy.The Hierarchical Long-Short Manifold (H-LSM) is Alluci’s 4‑tier stateful memory architecture. Managed by HLSMManager (backend/memory/hlsm_manager.py) augmented by the Markov Trace & Spectral Geometry Engine (backend/memory/markov_trace.py).
H-LSM enables the agent to retain personal and organizational memory over time without context‑window bloat, context degradation, or hallucinations.
H-LSM operates across four cognitive memory storage tiers:
• L0 Working Memory: Ultra‑fast, session‑level expiring context backed by Redis (Key‑Value) with automatic zero-config fallback to SQLite table hlsm_working.
• L1 Episodic Memory: Full chat turns, interaction history, and episodic event logs backed by SQLite table hlsm_episodic with a high‑performance SQLite FTS5 full‑text search index (hlsm_episodic_fts).
• L2 Semantic Memory: Long‑term vector embeddings for retrieval‑augmented generation (RAG), backed by Sentence‑Transformers (all‑MiniLM‑L6‑v2) and KùzuDB graph nodes (polytope_data.kuzu).
• L3 Knowledge Graph: Permanent structured entity‑relationship graph nodes backed by the KùzuDB embedded graph database engine (polytope_data.kuzu).
Tri-Hybrid Reciprocal Rank Fusion (RRF $k=60$):
• Parallel Asynchronous Retrieval: Dispatches queries concurrently across L1 SQLite FTS5 ($w=1.0$), L2 MiniLM Dense Vectors ($w=1.2$), and L3 KùzuDB Knowledge Graph Entities ($w=1.4$).
• Authoritative Score Fusion: Harmonizes multi-modal score distributions using the standard RRF constant ($k=60$):
$$\text{Score}{\text{RRF}}(d) = \sum{t \in {\text{L1}, \text{L2}, \text{L3}}} \frac{w_t}{60 + \text{rank}_t(d)}$$
• Knowledge Graph Entity Injection: Automatically extracts retrieved entity relations from KùzuDB and injects them directly into prompt grounding contexts under structured entity headers (── Knowledge Graph Entities ──).
Markov Trace Multi-Hop Rescoring & Scale-Dependent Spectral Geometry (markov_trace.py):
• Schur Complement Trace Operator: Uncovers multi-hop hidden excursion pathways across visible and hidden memory nodes:
$$\text{Tr}_A(P) = A + B(I - C + \epsilon I)^{-1} D$$
boosting visible candidate scores (80% direct semantic relevance + 20% topological excursion boost) and promoting high-coupling hidden bridge nodes.
• Symmetrized Normalized Laplacian ($L_A$): Computes normalized Laplacian eigenvalues $\lambda_i \ge 0$, Fiedler algebraic connectivity ($\lambda_2$), and heat return probability $P_A(\sigma) = \frac{1}{|A|} \sum e^{-\sigma \lambda_i}$.
• Dynamic Context Depth Scaling: Derives the scale-dependent spectral dimension $d_s^A(\sigma) = 2\sigma \frac{\sum \lambda_i e^{-\sigma \lambda_i}}{\sum e^{-\sigma \lambda_i}}$, dynamically expanding retrieval depth (max_per_tier) when mixing is sparse ($d_s^A > 1.5$).
Alluci utilizes a specialized "Training Sandbox" mode that leverages the Unsloth library (optimized for 80% less VRAM usage) to perform Supervised Fine‑Tuning (SFT) directly on your hardware.
When the system detects low cognitive load (you are asleep or away), the daemon halts external polling and reallocates 100% of hardware resources to internal evolution:
j_space_simulator.py) simulating boundary recovery, 3) Teacher Synthesis (air-gapped local 31B Dense model instruction pair synthesis), 4) Cognitive Distillation (Socratic questioning of episodic logs into permanent Semantic Truths), and 5) Preference Harvesting.dpo_harvester.py, markov_trace.py): Automatically harvests teacher-student preference triplets $(x, y_w, y_l)$ from:
failed_plan $\to$ successful_plan).reverted_code $\to$ repaired_code).The Soul Manifest serves as Alluci’s core behavioral blueprint and active cognitive runtime engine. Moving beyond static system prompts and plain .md files, Alluci decouples persona configuration into a stateful, auditable Soul Manifest that actively drives model sampling parameters, dynamic neural-weight adapters, zero-trust security gates, and bio-affective attunement loops in real time.
apply_lora_adapter): Rather than cluttering context windows with lengthy text instructions, Soul Profiles hot-swap compiled LoRA neural weights (agent_{id}_lora.safetensors) directly into VRAM on the fly without restarting the inference engine process.contentmultimap) for portable identity, with local AES-256-GCM envelope encryption for air-gapped sovereignty.identityCore), voice profiles (voiceProfile), system directives, and boot sequence parameters (bootSequence).SoulPreferences).active_skill_ids) and executable tool IDs (active_tool_ids) directly to the soul context, restricting or expanding agency based on active persona.SoulProfileRecord): Supports creating, updating, listing, and switching between pre-configured Soul Profiles stored in the local SQLite database (/soul/profiles), allowing users to toggle between executive, technical, creative, or analytical personas on the fly./soul/preview): Features a dedicated preview endpoint that executes candidate prompts through the current Soul Manifest before committing updates to active agent sessions, providing instant feedback on persona alignment and safety constraints.Traditional AI agent frameworks define "Skills" and "Tools" as static markdown text files (SKILL.md) or simple string descriptions embedded in system prompts. This legacy approach suffers from severe limitations: high context window bloat, steep API token costs, floating-point non-determinism, soft pattern-matching hallucinations, and a complete lack of runtime execution validation.
The Alluci Sovereign Agent completely re-architects Skills and Tools from passive text documents into Active Cognitive Python Runtimes and Skill-Specific Deterministic Tool Engines. Managed by the SkillManager (backend/routers/skills.py) and ToolRegistry (backend/routers/tools.py), Skills and Tools operate as compiled, stateful runtimes driven by five deterministic cognitive parameters (Knowledge, Mindsets, Methodologies, Chains of Thought, and Logic), zero-trust security gates, and hardware biometric governance.
When creating or instantiating a Skill, the Skill Builder Engine configures five deterministic parameters that govern the active Python Skill Runtime:
L3 Knowledge Graph), semantic embeddings (L2 Vector RAG), and indexed interaction history (L1 Episodic FTS5) without factual drift.SEC-005 int16 clamping) and discrete integer simplicial boundary operators ($\partial_k: C_k \to C_{k-1}$), eliminating floating-point non-determinism across Host CPU, CUDA GPU, and Apple Metal GPU runtimes.LoRAForge (backend/engine/lora_forge.py) crystallizes these trajectories into native PyTorch/MLX LoRA adapters (e.g., coding_lora.safetensors, legal_lora.safetensors).apply_lora_adapter(), delivering domain expertise with zero prompt-window bloat.AntNetworkProtocol): Skill execution paths are mapped into Betti topological barcodes ($\beta_0, \beta_1, \beta_2$) and broadcast over the Verus P2P network, allowing multi-agent constellations to share skill intelligence zero-knowledge across devices.Tools in Alluci are Skill-Specific Deterministic Tool Engines backed by sandboxed Python runtimes, Model Context Protocol (MCP) servers, JSON-RPC daemons, and compiled C++ kernels:
alluci_vault/tools/ and core_tools/) with explicit JSON Schema contracts, rate limits, and timeout boundaries.WebSearchAdapter): Decomposes complex research queries into parallel orthogonal search vectors executed concurrently with strict 4.0s timeouts, URL deduplication, and a dedicated 24-hour TTL SQLite cache (ResearchDossierCache in backend/data/research_cache.db), serving repeat lookups with 0ms latency and real markdown citations.Alluci implements a zero-trust, hardware-anchored security model that couples system execution directly to physical human presence and device liveness. Rather than relying solely on software passwords or API key tokens, Alluci enforces multi-modal biometric liveness, hardware kill switches, interactive executive governance, and isolated cryptographic vault containers to guarantee absolute data sovereignty and prevent unauthorized execution.
backend/routers/gemini.py).SecurityInterventionModal.tsx), requiring explicit administrative authorization ([ Approve & Execute Action ]) before operations proceed.BioTelemetryAuth / PPN-017)BioTelemetryAuth.is_on_wrist=True) and active heart rate pulse before executing sensitive operations (banking, db_write, file_overwrite, os_exec, crypto_tx).REQUIRE_WATCH_TELEMETRY=True), loss of wrist contact or missing pulse instantly activates the Sovereign Kill Switch—aborting execution, locking the agent, and encrypting active working memory.PPN-018)Alluci is built natively around the Verus DREAM (Decentralized Real-time Encrypted Application Model) framework. By abandoning centralized cloud application servers, API keys, and third-party database proxies, Alluci pairs local-first machine intelligence with VerusID self-sovereign identities, structured VDXF data namespaces, local blockchain nodes, and encrypted peer-to-peer (P2P) state synchronization.
identity@).verus_rpc.py)verus_get_info, verus_get_identity).verus_send_currency), and creates decentralized marketplace orders (verus_make_offer) natively on-device.vdxf_store.py)verus_get_vdxf_id) to structure application data, skill manifests, and agent configurations without vendor lock-in.contentmultimap): Stores and retrieves encrypted agent manifests and peer messages directly on the VerusID content multimap (VDXFStore), creating a portable, decentralized state storage layer.audit_ledger.py / verus_txid)AuditLedger and H-LSM memory manifolds.verus_txid): Anchors state integrity hashes and executive action summaries directly to the Verus blockchain (verus_txid and vdxf_key), generating an un-alterable, mathematically verifiable audit log of agent history.AntNetworkProtocol)AntNetworkProtocol (Alluci_Ant_v1) over Verus VDXF messaging channels to coordinate multi-agent constellations across distributed devices.For enterprise environments requiring strict GDPR or Schrems II compliance, the Sovereign Agent utilizes a "Defense in Depth" proxy strategy:
DATA_REGION="EU" in the environment mathematically prevents any cloud egress without passing through the pseudonymization proxy.ENFORCE_EU_ENDPOINTS=True forces Azure OpenAI and Google Vertex API clients to dynamically route to EU-based datacenters on the fly.[!NOTE] See the full Data Residency & Compliance Architecture for legal and technical implementation details.
Alluci includes an integrated Usage & Cost Analytics Engine (UsageTracker in backend/analytics.py and backend/routers/usage.py) that delivers real-time token tracking, financial telemetry, multi-provider model cost rollups, and spending optimization across all cloud and local execution paths.
/usage)/usage/summary), daily usage rollups (/usage/daily), and turn-by-turn cumulative session curves (/usage/sessions/{session_key}/timeseries)./usage/sessions): Provides session-level audit metrics detailing agent identities, provider distributions, model selection, total turn counts, and timestamp logs.AIRGAPPED, SENSITIVE, PUBLIC)./usage/sessions/export/csv)The Sovereignty Level Wizard makes onboarding seamless. Choose between Cloud-only (Level 1), Local Edge (Level 2), or the Full Sovereign Base (Level 3).
Before installing Alluci, verify that your host environment meets the following requirements:
npm (v10+)pipclang++ on macOS, g++ on Linux, MSVC on Windows), make, git, and lsof (Required to compile native DPK security kernels)mlx, mlx-lm, mlx-vlm, mlx-whisper) leveraging Unified Memorytorch>=2.4.0), sentence-transformers, or llama.cpp GGUF bindings via local_bridge.pyhuggingface_hub CLI for downloading model weights from HuggingFace (Alluci Models)kuzu embedded C++ engine) powering H-LSM Knowledge Graphv7.0+, optional for high-speed L0 Working Memory; automatically falls back to SQLite in zero-config LITE_MODE)verusd node RPC daemon for VerusID decentralized identity, VDXF content maps, and on-chain audit ledger anchoringbridges/iwatch.py) or wearable webhooks (Garmin, Whoop, Oura) for bio-affective stress attunement and the Sovereign Kill SwitchAlluci features an automated, hardware-aware model downloader (scripts/download_models.py).
Hardware-Aware Model Provisioning (Online Setup):
Running ./scripts/setup_sovereign_stack.sh triggers HardwareProfiler.get_system_profile(). The profiler scans host System RAM, VRAM, and GPU architecture, automatically downloading the optimal model weights directly from HuggingFace (Alluci Models) into your local mirror_cache/:
TIER_0_ULTRA through TIER_4_EDGE).EDGE_2B_4BIT) for draft-verification token acceleration.all-MiniLM-L6-v2) for local RAG vector search.Air-Gap Activation (100% Offline Sovereignty):
Once the setup script outputs [ INFO ]: Setup Complete, all model weights, tokenizer manifests, and embedding models are cached locally. You can physically disconnect network cables or disable Wi-Fi, and the Sovereign Agent will execute indefinitely offline with zero external network dependencies.
Automated Stack Initialization
chmod +x scripts/setup_sovereign_stack.sh
./scripts/setup_sovereign_stack.sh
Managing the Stack via Makefile The easiest way to run the entire stack locally is using our pre-configured Makefile:
make init # Initialize .env, virtualenv, and install dependencies via bootstrap_all.sh
make start # Cleanly start Backend (Port 8000) and Frontend (Port 3000)
make status # Verify port 8000/3000 status and active services
make doctor # Run diagnostic check on toolchain and local environment (scripts/verify_local.py)
make stop # Gracefully terminate active background processes
Manual Startup Alternative:
source .venv/bin/activate && uvicorn backend.app:app --port 8000 --host 0.0.0.0npm run dev -- --port 3000 --host 0.0.0.0Open http://localhost:3000 to launch the Alluci Sovereign Gateway. Upon first launch, the Sovereignty Wizard will guide your configuration.
The Sovereign Agent uses a strictly local .env file to seed its Verus Vault and configuration parameters:
cp .env.example .env
Configure core environment keys in .env:
POLYTOPE_MASTER_KEY: Master seed for AES-256 vault encryption and 2FA secrets.JWT_SECRET_KEY: Used for secure session token signing.VERUS_ID_IDENTITY: Sovereign VerusID identity handle (YourIdentity@).VERUS_ID_PRIVATE_KEY: Ed25519 private key seed for executive manifest signing.REQUIRE_WATCH_TELEMETRY: Set to True to enforce biometric kill switch liveness checks.DATA_REGION: Set to EU to enforce the SecureProxy PII firewall.ENFORCE_EU_ENDPOINTS: Set to True for strict physical EU cloud datacenter routing.Alluci incorporates a rigorous quality gate to guarantee local system stability, zero-trust security, and immutable supply-chain integrity:
make quality
The Quality Gate Executes:
scripts/production_readiness/preflight.sh).pytest backend/tests/ -v) and performance benchmarks (pytest backend/tests/performance/test_benchmarks.py).npm audit, pip-audit, and static secret detection scanning.reports/ (generate_release_report.py).To run tests manually:
source .venv/bin/activate
pytest backend/tests/ -v
The DEBUG environment variable controls system diagnostic verbosity:
DEBUG=False): Mutes internal exception tracebacks, masks FastAPI error details, and sanitizes JSON-RPC response payloads.DEBUG=True): Enables full exception tracebacks, detailed validation data, and verbose topological log output.Set DEBUG=True in your .env or export the variable locally to enable detailed diagnostics during development.
Copyright © 2026 Alluci-Ai. All Rights Reserved.
This software and associated documentation files (the "Software") are the proprietary property of Alluci-Ai. Unauthorized copying, reproduction, distribution, modification, or use of this Software, via any medium, is strictly prohibited without the express written permission of Alluci-Ai.
For information on our strictly-gated proprietary contribution process, please review our Contribution Guidelines.
"Alluci-Polytope: Turning AI from a passive tool into a sovereign, affective partner."