xulcan 0.2.0

Xulcan Agent OS - A State-of-the-Art LLM Agent Framework

Xulcan

English 🇬🇧 · Spanish 🇲🇽

The Deterministic Operating System for AI Agents.

Xulcan is a strict, type-safe Agentic Operating System (Agentic OS) designed from the ground up for engineering and production environments. Based on the principles of Domain-Driven Design (DDD) and Cybernetics, it treats Agents as Data, History as an Immutable Ledger, and Execution as a deterministic state machine.

---

The Concept: The Agentic OS 🖥️

Understanding Xulcan is easy if you map it to classical computer architecture (Von Neumann). We separate the chaos of LLMs from the strictness of software engineering:

OS Module	The AI Equivalent	Description
CPU (ALU)	LLM Adapters	The models (Gemini, Ollama). They are stateless, isolated, and only process semantics to output intentions (ToolCalls).
Kernel / FSM	ProtoKernel	The execution loop. It manages token budgets, mitigates entropy, handles errors safely, and orchestrates the state machine.
RAM (Memory)	StateStore / Blackboard	Ephemeral shared memory. Allows passing huge payloads (like APIs or PDFs) by reference instead of burning LLM tokens.
Peripherals	Sandbox / Network	The "Hands". Sandboxed Docker containers and network executors that safely interact with the real world.
Hard Drive	The Ledger	An immutable, append-only Event Sourcing log of every thought and action. Enables forensic auditability.

---

Infrastructure as Code (IaC) for Agents 📜

Xulcan separates the Software Engineering from the Prompt Engineering. Agents are not hardcoded in Python; they are defined in YAML manifests.

# manifests/analyst_agent.yaml
name: "Financial Analyst"
model_provider: "google"
model_name: "gemini-2.5-flash"
system_prompt: "You are an expert analyst. Use your sandbox to calculate..."
tools:
  - name: "network_api_get"
    enabled: true
  - name: "sandbox_run_bash"
    enabled: true

Just load the manifest and let the OS handle the rest.

---

Quick Start

Prerequisites

• Docker & Docker Compose
• Make (Linux/Mac/WSL2)
• Python 3.11+

Option A: Standalone Usage (Python Script)

Perfect for testing and running agents locally.

# 1. Clone & Install
git clone https://github.com/ActraStride/xulcan.git
cd xulcan
pip install -e .

# 2. Run the demo agent
python demo.py

Option B: Server Deployment (FastAPI)

Launch the full Nivel 2 B2B infrastructure with Postgres and Redis.

# Start the Xulcan API and Databases
make dev

# Verify the OS is alive
curl http://localhost:8000/health/live

---

Project Structure

The codebase strictly follows Hexagonal Architecture. Upper levels depend on lower levels, never the reverse.

xulcan/
├── app/
│   ├── xulcan/
│   │   ├── core/          # Level 0: Primitives & Economics
│   │   ├── protocol/      # Level 1: Messages & Tools Schemas
│   │   ├── blueprint/     # Level 1: YAML Loaders & Agent Naming
│   │   ├── ledger/        # Level 2: Event Sourcing & Auditability
│   │   ├── memory/        # Level 2: StateStore (Blackboard)
│   │   ├── llm/           # Level 3: Stateless Adapters (Gemini, Ollama)
│   │   ├── tools/         # Level 3: Executors (Docker Sandbox, Network)
│   │   └── kernel/        # Level 3: The FSM Runtime Engine
│   └── main.py            # FastAPI Entrypoint (Wrapper)
├── manifests/             # 📜 IaC Agent Definitions (YAML)
├── demo.py                # Standalone Client Example
├── tests/                 # Pytest suite
├── docker-compose.yaml
└── Makefile

---

Why Xulcan?

1. Strict Entropy Control: The LLM does not dictate the flow. The Kernel's Finite State Machine (FSM) traps errors, prevents infinite loops, and forces determinism.
2. True Physical Isolation: Code generated by the agent is executed in ephemeral, lazy-loaded Docker containers (SandboxExecutor) with zero risk to the host machine.
3. Forensic Auditability: The Ledger records every token, latency, and tool execution. You never wonder "Why did the agent do that?". You have the mathematical proof.
4. Fractal Swarms: Agents can invoke other Blueprints as tools (SubAgentExecutor), creating hierarchical teams natively.

---