# ACT Kernel

**Deterministic Execution Layer for AI Agents**

[![PyPI version](https://badge.fury.io/py/act-kernel.svg)](https://badge.fury.io/py/act-kernel)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[English](README.md) | [中文](README.zh.md)

> A deterministic-first execution kernel that transforms natural language intent into safe, observable, and governable tool execution processes.

## 🎯 Core Philosophy

ACT Kernel's goal is not to make models "think better," but to enable Agents to **execute stably, accurately, and quickly**.

## ✨ Key Features

- **Deterministic Routing**: Rule/prefix/regex-based fast tool path resolution
- **Safe Execution**: Built-in timeout, retry, circuit breaker, rate limiting, and quota control
- **Structured Response**: Unified Envelope protocol for easy upstream consumption
- **Token Bucket Rate Limiting**: Per-tool / per-action support
- **Shared Thread Pool Timeout**: Reduces executor creation/destruction overhead
- **Actual Retry Count**: For monitoring and scheduling
- **Request Tracing**: Support for request_id
- **Extensible Architecture**: Middleware chain entry reserved for v1.2

## 🚀 Quick Start

### Requirements

- Python 3.10+
- No external dependencies for core functionality

### Installation

```bash
# Install from PyPI (recommended)
pip install act-kernel

# With CrewAI integration
pip install act-kernel[crewai]
```

Or install from source:

```bash
# Clone and install from source
git clone https://github.com/deepseek609609-collab/act-kernel-agent.git
cd act-kernel-agent
pip install -e .

# With CrewAI integration
pip install -e ".[crewai]"
```

### Define a Tool

```python
from act import tool

@tool(
    name="weather.get_current",
    timeout_ms=1500,
    rate_limit=5,
    description="Get current weather for a city"
)
def get_weather(params):
    return {
        "city": params.get("city", "Beijing"),
        "temperature": 22,
        "condition": "sunny"
    }
```

### Run Example

```bash
python examples/demo_crewai_agent.py
```

## 📋 Execution Environment

### System Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| Python | 3.10 | 3.11+ |
| RAM | 512 MB | 1 GB |
| CPU | 1 core | 2+ cores |
| Disk | 100 MB | 500 MB |

### Runtime Environments

ACT Kernel can run in various environments:

- **Local Development**: Direct Python execution
- **Docker Container**: Lightweight containerized deployment
- **Cloud Functions**: AWS Lambda, Azure Functions, GCP Cloud Functions
- **Kubernetes**: Microservices architecture
- **Edge Devices**: Raspberry Pi, Jetson Nano (with Python 3.10+)

### Environment Variables

```bash
# Optional: Set default timeout (milliseconds)
export ACT_DEFAULT_TIMEOUT_MS=5000

# Optional: Set default retry count
export ACT_DEFAULT_RETRIES=2

# Optional: Enable debug logging
export ACT_DEBUG=1
```

## 📦 Response Structure

All calls return a unified Envelope:

```json
{
  "version": "1.0",
  "intent": {
    "raw_intent": "weather.get_current",
    "request_id": "uuid",
    "tool": "weather",
    "action": "get_current"
  },
  "execution": {
    "status": "ok",
    "latency_ms": 12,
    "queue_ms": 0,
    "retries": 0,
    "breaker_state": "closed",
    "timeout_ms": 1500,
    "cached": false,
    "quota_requested": 1,
    "quota_consumed": 1,
    "quota_remaining": 9,
    "node": "local"
  },
  "payload": {...},
  "error": null
}
```

## 🏷️ Status Definitions

- `ok`: Execution successful
- `timeout`: Execution timed out
- `error`: Tool error or system error
- `rejected`: Rejected (rate limit, circuit breaker, permission denied)
- `degraded`: Degraded execution

## 🚨 Error Codes

| Code | Description |
|------|-------------|
| `routing.not_found` | No route found for intent |
| `execution.timeout` | Execution exceeded timeout |
| `execution.circuit_open` | Circuit breaker is open |
| `execution.retry_exhausted` | All retry attempts failed |
| `validation.invalid_params` | Invalid parameters |
| `permission.denied` | Permission denied |
| `quota.exceeded` | Quota exceeded |
| `tool.unavailable` | Tool temporarily unavailable |
| `tool.error` | Tool execution error |
| `internal.error` | Internal system error |

## 📁 Project Structure

```text
act-kernel/
├── act/                    # Main package
│   ├── kernel.py          # Core ACTKernel class
│   ├── protocol.py        # Protocol definitions
│   ├── tooling.py         # Tool decorators
│   └── adapters/          # Framework adapters
├── examples/              # Usage examples
├── docs/                  # Documentation
├── tests/                 # Test suite
├── tools/                 # Built-in tools
├── agent.py               # Interactive agent
├── README.md              # This file
├── README.zh.md           # Chinese version
├── CHANGELOG.md           # Change log
├── CONTRIBUTING.md        # Contribution guide
├── SECURITY.md            # Security policy
├── LICENSE                # MIT License
└── pyproject.toml         # Package configuration
```

## 📚 Documentation

- [ACT Protocol v1.1](docs/ACT_PROTOCOL_v1.1.md) - Detailed protocol specification
- [Architecture](docs/ARCHITECTURE.md) - System architecture
- [Roadmap](docs/ROADMAP.md) - Future development plans

## 🤝 Contributing

We welcome contributions in:

- New tool adapters
- Middleware implementations
- Test cases
- Performance benchmarks
- Documentation improvements

Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## 🔒 Security

For security concerns, please see [SECURITY.md](SECURITY.md).

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.

## 🌟 Why ACT Kernel?

Traditional Agent issues:

- Unstable tool calls
- Scattered timeout, retry, rate limiting logic
- Inconsistent return formats
- Lack of isolation between tools
- Difficult unified observability and governance

ACT Kernel unifies these capabilities into an **execution protocol layer**.

---

<p align="center">
  Made with ❤️ for deterministic AI execution
</p>
