Metadata-Version: 2.4
Name: iap-amcs
Version: 0.1.0
Summary: Agent Memory Canonicalization Standard (AMCS) reference package
Author: AMCS Contributors
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: httpx>=0.27; extra == "api"
Dynamic: license-file

# AMCS-0.1

Agent Memory Canonicalization Standard (AMCS) reference implementation.

## Install

```bash
python -m pip install -e ".[dev,api]"
```

If you only need core library features:

```bash
python -m pip install -e ".[dev]"
```

## Adopt In 1 Hour

1. Create a SQLite store.
2. Append events through `AMCSClient`.
3. Read the memory root.
4. Verify the chain.
5. Optionally encrypt payload fields before append.

## Minimal Append

```python
from amcs import AMCSClient, SQLiteEventStore

store = SQLiteEventStore("./amcs.db")
client = AMCSClient(store=store, agent_id="agent-1")

result = client.append("interaction.append", {"message": "hello"})
print(result.sequence, result.event_hash, result.memory_root)
```

## Verify Chain

```python
from amcs import verify_chain

result = verify_chain(store, "agent-1")
assert result.ok
```

## External Root Checkpoint (Optional)

Create a signed root receipt for external anchoring (for example: publish to an immutable log).

```python
from amcs import b64encode, generate_keypair

private_key, public_key = generate_keypair()
checkpoint = client.create_root_checkpoint(
    signer_private_key_b64=b64encode(private_key),
    signer_kid="registry-main",
)
assert client.verify_root_checkpoint(
    checkpoint=checkpoint,
    signer_public_key_b64=b64encode(public_key),
)
```

## Verification & Tamper Detection

For a full end-to-end tamper detection scenario, see:
- `tests/test_sdk_append_verify.py`

## Encrypt Field (Optional)

```python
from amcs import encrypt_field

enc = encrypt_field(
    b"secret",
    key,
    "kid-1",
    {"agent_id": "agent-1", "event_id": "evt-1", "event_type": "interaction.append"},
)
```

## Canonical JSON

```python
from amcs import canonical_bytes, canonical_dumps

event = {"b": 1, "a": 2}
text = canonical_dumps(event)  # {"a":2,"b":1}
data = canonical_bytes(event)  # UTF-8 bytes
```

## Optional API Service

```python
from amcs.api import create_app

app = create_app("./amcs.db")
```

The API dependencies are installed with:

```bash
python -m pip install -e ".[api]"
```

## Examples

- `examples/minimal_append.py`
- `examples/action_invoke.py`
- `examples/encrypted_interaction.py`

## Manual Acceptance Test (10 Minutes)

Run the human-legible acceptance test:

```bash
./scripts/manual_acceptance_test.sh
```

Detailed runbook:
- `docs/manual-acceptance-test-10min.md`
