theus 3.0.1

Reliable, Rust-Powered Agentic AI Framework with Transactional Memory.

Theus Framework

"Safe architecture for AI-assisted development. Powered by Rust."

---

🧭 Where do I start?

Theus is vast. Use our Interactive Documentation Map to find your path:

• 🚀 I want to build an Agent now: Go to Quickstart
• 🤖 I am an AI Assistant: Go to AI Tutorials
• 🏗️ I want to check architecture: Go to Specs
• 🎓 I want to learn from scratch: Go to Tutorials

---

� Why Theus?

"Build with confidence. Your AI assistant writes the code—Theus makes sure it's safe."

Whether you're vibe coding with an AI assistant, building a complex agent, or crafting production software that needs to last for years—Theus has your back.

For Vibe Coders & AI-Assisted Development

You focus on what you want to build. Let your AI write the logic. Theus automatically ensures:

• Every function declares exactly what data it reads and writes
• No hidden side effects or surprise mutations
• If something goes wrong, it rolls back cleanly

For Teams Who Care About Maintainability

Come back to your code in 2 years. You'll thank yourself:

• Explicit Contracts: Every @process is self-documenting
• Transparent State: Know exactly where your data lives and who can touch it
• Built-in Audit: Validate business rules at the boundary, not scattered in code

For Safety-Critical Applications

When bugs aren't just annoying—they're costly:

• Transaction Safety: Automatic rollback on failure
• Zero-Trust Memory: Processes can't access data they didn't declare
• Industrial Audit: Block, warn, or stop based on configurable rules

---

📦 Installation

Theus v3.0 requires Python 3.14+ to leverage Sub-interpreter support.

pip install theus

---

⚡ Quick Start

Option 1: Use a Template (Recommended)

# Create a new project with the E-Commerce demo (full-featured)
py -m theus.cli init my_app --template ecommerce
cd my_app
python main.py

This creates a complete runnable demo with: Orders, Payments, Heavy Zone, Audit Rules, and Workflow.

Option 2: Manual Setup

from theus import TheusEngine, process

# 1. Define a Process with Contract
@process(
    inputs=['domain.accounts'],
    outputs=['domain.accounts'],
    errors=['ValueError']
)
def transfer(ctx, from_user: str, to_user: str, amount: int):
    if amount <= 0:
        raise ValueError("Amount must be positive")
    
    accounts = ctx.domain.accounts
    if accounts.get(from_user, 0) < amount:
        raise ValueError("Insufficient funds")
    
    accounts[from_user] -= amount
    accounts[to_user] = accounts.get(to_user, 0) + amount
    return accounts

# 2. Initialize Engine
from src.context import DemoSystemContext
engine = TheusEngine(DemoSystemContext(), strict_mode=True)
engine.register(transfer)

# 3. Execute with Transaction Safety
result = engine.execute(transfer, from_user="Alice", to_user="Bob", amount=500)

💡 Available Templates: standard, ecommerce, hybrid, agent, minimal Run py -m theus.cli init --help to see all options.

---

🔄 Workflow: Flux DSL

v3.0 introduces Flux DSL - a declarative YAML language for workflow control.

# workflows/main.yaml
steps:
  - process: "initialize"
  
  - flux: if
    condition: "domain['is_valid'] == True"
    then:
      - "process_data"
      - "save_result"
    else:
      - "handle_error"
  
  - flux: while
    condition: "domain['items_left'] > 0"
    do:
      - "process_next_item"

Execute with:

engine.execute_workflow("workflows/main.yaml")

---

🛠️ CLI Tools

Theus provides a powerful CLI suite to accelerate development and maintain architectural integrity.

• py -m theus.cli init <project_name>: Scaffolds a new project with the standard V3 structure.
• py -m theus.cli audit gen-spec: Scans your @process functions and automatically populates specs/audit_recipe.yaml.
• py -m theus.cli audit inspect <process_name>: Inspects the effective audit rules for a process.
• py -m theus.cli schema gen: Generates specs/context_schema.yaml from your Python Dataclass definitions.
• py -m theus.cli check: Runs the POP Linter to enforce architectural purity.

---

🧠 Advanced Architecture

The Transaction Engine

Theus uses a Hybrid Transaction Model:

• Scalars: Updated in-place with an Undo Log (for speed).
• Collections: Updated via Shadow Copy (for safety). If a process crashes or is blocked by Audit, Theus rolls back the entire state instantly.

The Heavy Zone (Optimization)

For AI workloads (Images, Tensors) > 1MB, use heavy_ variables.

• Behavior: Writes bypass the Transaction Log (Zero-Copy).
• Trade-off: Changes to Heavy data are NOT reverted on Rollback.

🚀 High Performance Training

For Pure Training Loops where Transaction safety is overkill:

engine = TheusEngine(sys_ctx, strict_mode=False)

• Effect: Completely disables Rust Transaction Layer (Zero Overhead).
• Performance: Native Python execution speed.

---

📚 Documentation

• POP Manifesto: The philosophy behind Process-Oriented Programming.

---

⚖️ License

• Software: MIT License.
• Whitepaper: CC-BY 4.0.

Maintained by: Hoàng Đỗ Huy