Metadata-Version: 2.4
Name: agentmatrix-core
Version: 0.7.0.51
Summary: Core execution engine for building AI agent applications — MicroAgent, AgentShell protocol, Cerebellum, and skill system
Author: Agent-Matrix Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/webdkt/agentmatrix
Project-URL: Documentation, https://github.com/webdkt/agentmatrix/docs/core
Project-URL: Repository, https://github.com/webdkt/agentmatrix
Project-URL: Issues, https://github.com/webdkt/agentmatrix/issues
Keywords: agents,ai,llm,framework,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: Jinja2>=3.1.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# agentmatrix-core

**Let LLMs think. Don't make them write JSON.**

A Python execution engine for building AI agent applications. Separates reasoning from formatting: the large model thinks in natural language, a dedicated module handles the structured output.

---

## What It Is

`agentmatrix-core` provides the execution engine behind AgentMatrix. It includes:

- **MicroAgent** — A task execution engine with think-negotiate-act loop
- **AgentShell Protocol** — Clean boundary between execution and I/O
- **Cerebellum** — Intent parsing and parameter negotiation
- **Action System** — Pluggable skill registry and execution
- **SessionStore** — Conversation persistence
- **Auto-Compression** — Working Notes for arbitrarily long tasks
- **Signal System** — Event-driven communication

The core knows nothing about desktop apps, file systems, or networks. All external interaction goes through the `AgentShell` protocol, which you implement for your target environment.

---

## Install

```bash
pip install agentmatrix-core
```

Requires Python 3.12+.

---

## Quick Example

```python
from agentmatrix import AgentMatrix, Email

# Create the runtime
matrix = AgentMatrix("./MatrixWorld")

# Send an email to an agent
email = Email(
    sender="User",
    recipient="Researcher",
    subject="Search for Python 3.13 features",
    body="Find and summarize the major new features in Python 3.13"
)

# Dispatch via PostOffice
await matrix.post_office.dispatch(email)
```

For a complete minimal example implementing `AgentShell`, see the CLI tutorial in the repository.

---

## Architecture

```
┌─────────────────────────────────────────────┐
│  Your App (Desktop / CLI / Server)          │
├─────────────────────────────────────────────┤
│  AgentShell Protocol (you implement this)   │
├─────────────────────────────────────────────┤
│  MicroAgent Engine (this package)           │
│  - Brain (reasoning in natural language)    │
│  - Cerebellum (intent → action params)      │
│  - Action Registry                          │
│  - SessionStore                             │
└─────────────────────────────────────────────┘
```

---

## Key Design

- **No JSON output required** — Brain reasons in plain text
- **Dynamic skill composition** — Mixins assembled at runtime per task
- **Checkpoint-based pause/resume** — Cooperative, not forced interruption
- **Auto context compression** — LLM-generated Working Notes prevent overflow
- **Nested MicroAgents** — Tasks can spawn sub-tasks with different skill sets

---

## Documentation

- Full docs: https://github.com/webdkt/agentmatrix/docs
- CLI tutorial: https://github.com/webdkt/agentmatrix/tree/main/tutorial/cli-agent

---

## License

Apache License 2.0
