# Xulcan

<p align="center">
    <a href="README.md">English 🇬🇧</a>
    · <a href="docs/README.es.md">Spanish 🇲🇽</a>
</p>

**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.

[![License](https://img.shields.io/badge/license-AGPLv3-blue.svg)](LICENSE)
[![Architecture](https://img.shields.io/badge/Architecture-Event%20Sourced-purple.svg)]()
[![Core](https://img.shields.io/badge/Core-Frozen%20v1.0-green.svg)]()
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

---

## 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.

```yaml
# 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.
```bash
# 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.
```bash
# 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.

```text
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.

***