Metadata-Version: 2.1
Name: theus
Version: 2.1.4
Summary: Theus Agentic Framework - Industrial Grade Process-Oriented Programming (POP)
Home-page: https://github.com/dohuyhoang93/theus
Author: Do Huy Hoang
Author-email: dohuyhoangvn93@gmail.com
Project-URL: Source, https://github.com/dohuyhoang93/theus
Project-URL: Bug Tracker, https://github.com/dohuyhoang93/theus/issues
Keywords: ai,agent,pop,process-oriented,transactional,state-management,theus,framework,microkernel
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic >=2.0
Requires-Dist: pyyaml >=6.0
Requires-Dist: typing-extensions >=4.0

# Theus: Process-Oriented Operating System for Python

[![PyPI version](https://img.shields.io/pypi/v/theus.svg)](https://pypi.org/project/theus/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Paper License: CC-BY 4.0](https://img.shields.io/badge/Paper--License-CC--BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

> **"Data is the Asset. Code is the Liability. Theus protects the Asset."**

Theus is a next-generation architectural framework that treats your application not as a collection of objects, but as a **deterministic workflow of processes**. It introduces the **Process-Oriented Programming (POP)** paradigm to solve the chaos of state management in complex systems like AI Agents, Core Banking, and Industrial Automation.

---

## 🌪️ The Problem
In modern software (OOP, EDA, Microservices), the biggest source of bugs is **State Management**:
*   **Implicit Mutations:** Who changed `user.balance`? Was it the PaymentService or the RefundHandler?
*   **Race Conditions:** Transient events corrupting persistent data.
*   **Zombie State:** Old references pointing to stale data.
*   **Audit Gaps:** We log *what* happened, but we can't mathematically prove *why* it was allowed.

## 🛡️ The Theus Solution
Theus acts as a micro-kernel for your logic, enforcing strict architectural invariants at runtime:

### 1. The 3-Axis Context Model
State is no longer a "bag of variables". It is a 3D space defined by:
*   **Layer:** `Global` (Config), `Domain` (Session), `Local` (Process).
*   **Semantic:** `Input` (Read-only), `Output` (Write-only).
*   **Zone:**
    *   **DATA:** Persistent Assets (Replayable).
    *   **SIGNAL:** Transient Events (Reset on Read).
    *   **META:** Observability (Logs/Traces).

```
                                     [Y] SEMANTIC
                             (Input, Output, SideEffect, Error)
                                      ^
                                      |
                                      |
                                      |                +------+------+
                                      |               /|             /|
                                      +--------------+ |  CONTEXT   + |----------> [Z] ZONE
                                     /               | |  OBJECT    | |      (Data, Signal, Meta)
                                    /                | +------------+ |
                                   /                 |/             |/
                                  /                  +------+------+
                                 v
                            [X] LAYER
                     (Global, Domain, Local)
```

### 2. Zero-Trust Memory
*   **Default Deny:** Processes cannot access ANY data unless explicitly declared in a `@process` Contract.
*   **Immutability:** Inputs are physically frozen (`FrozenList`, `FrozenDict`).
*   **Isolation:** Signals cannot be used as Inputs for Business Logic (Architectural Boundary enforcement).

### 3. Industrial-Grade Audit
*   **Active Defense:** Rules (`min`, `max`, `regex`) are enforced at Input/Output Gates.
*   **Severity Levels:**
    *   **S (Safety):** Emergency Stop.
    *   **A (Abort):** Hard Stop Workflow.
    *   **B (Block):** Rollback Transaction.
    *   **C (Campaign):** Warning.
*   **Resilience:** Configurable tolerance thresholds (e.g., "Allow 2 glitches, block on 3rd").

---

## 📦 Installation

Theus requires **Python 3.12+** to leverage advanced typing and dataclasses.

```bash
pip install theus
```

---

## ⚡ Quick Start: Building a Bank

This example demonstrates Contracts, Zoning, and Transaction safety.

### 1. Define the Context (The Asset)
```python
from dataclasses import dataclass, field
from theus.context import BaseSystemContext

@dataclass
class BankDomain:
    # DATA ZONE: Persistent Assets
    accounts: dict = field(default_factory=dict) # {user_id: balance}
    total_reserves: int = 1_000_000
    
    # SIGNAL ZONE: Control Flow
    sig_fraud_detected: bool = False

@dataclass
class BankSystem(BaseSystemContext):
    domain: BankDomain = field(default_factory=BankDomain)
```

### 2. Define the Process (The Logic)
```python
from theus.contracts import process

@process(
    # STRICT CONTRACT
    inputs=['domain.accounts'],
    outputs=['domain.accounts', 'domain.total_reserves', 'domain.sig_fraud_detected'],
    errors=['ValueError']
)
def transfer(ctx, from_user: str, to_user: str, amount: int):
    # 1. Input Validation
    if amount <= 0:
        raise ValueError("Amount must be positive")
    
    # 2. Business Logic (Operating on Shadow Copies)
    # ctx.domain.accounts is a TrackedDict
    sender_bal = ctx.domain.accounts.get(from_user, 0)
    
    if sender_bal < amount:
        # Trigger Signal
        ctx.domain.sig_fraud_detected = True
        return "Failed: Insufficient Funds"

    # 3. Mutation (Optimistic Write)
    ctx.domain.accounts[from_user] -= amount
    ctx.domain.accounts[to_user] = ctx.domain.accounts.get(to_user, 0) + amount
    
    # 4. Invariant Update
    # (Note: reserves don't change in transfer, but we have write access just in case)
    
    return "Success"
```

### 3. Run with Safety (The Engine)
```python
from theus.engine import TheusEngine

# Setup Data
sys_ctx = BankSystem()
sys_ctx.domain.accounts = {"Alice": 1000, "Bob": 0}

# Initialize Engine
engine = TheusEngine(sys_ctx, strict_mode=True)

# 🚀 PRO TIP: Auto-Discovery
# Instead of registering manually: engine.register_process("transfer", transfer)
# You can scan an entire directory (Theus will find all @process functions):
# engine.scan_and_register("src/processes")

engine.register_process("transfer", transfer)

# Execute
result = engine.run_process("transfer", from_user="Alice", to_user="Bob", amount=500)

print(f"Result: {result}")
print(f"Alice: {sys_ctx.domain.accounts['Alice']}") # 500
```

---

## 🛠️ CLI Tools

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

*   **`theus init <project_name>`**: Scaffolds a new project with the standard V2 structure (`src/`, `specs/`, `workflows/`).
*   **`theus audit gen-spec`**: Scans your `@process` functions and automatically populates `specs/audit_recipe.yaml` with rule skeletons.
*   **`theus audit inspect <process_name>`**: Inspects the effective audit rules, side effects, and error contracts for a specific process.
*   **`theus schema gen`**: Infers and generates `specs/context_schema.yaml` from your Python Dataclass definitions.

---

## 🧠 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 Audit Recipe (`audit.yaml`)
Decouple your business rules from your code.

```yaml
process_recipes:
  transfer:
    inputs:
      - field: "amount"
        max: 10000        # Max transfer limit
        level: "B"        # Block transaction
    outputs:
      - field: "domain.total_reserves"
        min: 0            # Reserves must never be negative
        level: "S"        # Safety Interlock (Stop System)
```

### The Orchestrator (FSM)
Manage complex flows using `workflow.yaml`:
```yaml
states:
  IDLE:
    events:
      CMD_TX: "PROCESSING"
  PROCESSING:
    entry: "transfer"
    events:
      EVT_SUCCESS: "NOTIFY"
      EVT_FAIL: "IDLE"
```

---

## 📚 Documentation

*   **[POP Whitepaper v2.0](./Documents/POP_Whitepaper_v2.0.md):** The formal theoretical basis.
*   **[Theus Master Class](./Documents/tutorials/en/):** 15-Chapter Zero-to-Hero Tutorial.
*   **[AI Developer Guide](./Documents/AI_DEVELOPER_GUIDE.md):** Prompt context for LLMs.

---

## ⚖️ License

*   **Software:** [MIT License](https://opensource.org/licenses/MIT).
*   **Whitepaper:** [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/).

**Maintained by:** [Hoàng Đỗ Huy](https://github.com/dohuyhoang93)
