Metadata-Version: 2.4
Name: acta
Version: 0.1.0
Summary: File-based async message passing for AI agents. Maildir for LLMs.
Project-URL: Homepage, https://github.com/terry-li-hm/acta
Author-email: Terry Li <terry.li.hm@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,async,llm,message-passing,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# acta

File-based async message passing for AI agents. Maildir for LLMs.

```
pip install acta
```

## Why

AI agents (Claude, Gemini, Codex, OpenCode) need to communicate across sessions, platforms, and time. Existing frameworks (AutoGen, CrewAI, LangGraph) are synchronous, in-memory, and framework-locked.

ACTA is different: agents drop markdown files in a shared directory. Any agent on any platform can read and write. No server, no framework, no SDK. Just files.

## Core idea

- **Agents are commodity instances.** Every LLM invocation is interchangeable.
- **Skills are the identity.** Knowledge comes from what you load, not who you are.
- **Files are the communication layer.** Durable, cross-platform, survives reboots.

## Usage

### Python

```python
from acta import post, read, clear

# Skill posts a message for a human
post("Found NAV discrepancy", sender="avantis-verify", to="terry", severity="action")

# Another skill posts for a different skill
post("Fund details confirmed", sender="avantis-verify", to="ibkr-setup")

# Read messages for a specific recipient
msgs = read(to="terry")

# Clear when handled
clear(msgs[0]["id"])
```

### CLI

```bash
acta post "Found NAV discrepancy" --from avantis-verify --to terry -v action
acta list --to terry
acta clear 2026-03-20-1915-nav-discrepancy
acta archive --all
```

### Any LLM agent

No SDK needed. Any agent that can read/write files can participate:

```bash
# Post (any language, any platform)
cat > ~/notes/ACTA/2026-03-20-1915-message.md << 'EOF'
---
from: my-skill
to: all
severity: info
ts: 2026-03-20T19:15+0800
---

This is a message from any agent on any platform.
EOF

# Read
ls ~/notes/ACTA/*.md
```

## Message format

```markdown
---
from: avantis-verify
to: terry
severity: action
ts: 2026-03-20T19:15+0800
---

Found NAV discrepancy — KIID shows 0.42% TER but Morningstar shows 0.45%.
```

## Configuration

Set `ACTA_DIR` to change the board location (default: `~/notes/ACTA`):

```bash
export ACTA_DIR=/path/to/shared/board
```

## License

MIT
