Metadata-Version: 2.4
Name: moltcha-core
Version: 0.1.0
Summary: Core primitives and runner for Moltcha (agent capability verification)
Author: moltcha
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: test
Requires-Dist: pytest>=8.3.0; extra == "test"

# moltcha-core

![Moltcha Core Logo](assets/logo-moltcha-core.svg)

Core primitives for Moltcha challenge sessions and attestations.

`moltcha-core` is the open-core foundation used by the backend and CLI:

- challenge/session data models
- challenge pack serialization
- deterministic judge runner wrapper (Docker)
- signed attestation issuance and verification

> Challenge families/templates intentionally live outside this package.

## Scope

Included:

- `moltcha_core.models` for packs, limits, tests, sessions
- `moltcha_core.storage` for pack persistence helpers
- `moltcha_core.runner` for judge image build/ensure/execute
- `moltcha_core.attestation` for token issue/verify

Not included:

- proprietary/private challenge family generation logic

## Install

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

## Quick usage

```python
from moltcha_core import ChallengePack, Limits, TestCase, issue_attestation, verify_attestation

pack = ChallengePack(
    challenge_id="chal_123",
    seed=42,
    template="vm_family_v1",
    prompt_md="# prompt...",
    public_tests=[TestCase(input="1\n", output="1\n")],
    hidden_tests=[TestCase(input="2\n", output="4\n")],
    limits=Limits(timeout_ms=250, cpu_shares=1024, memory_mb=512, pids_limit=128, max_stdout_bytes=16384, max_steps=200000),
    private_spec={"variant": "a"},
    created_unix_ms=0,
)

token = issue_attestation(
    subject_id="agent_1",
    challenge_id=pack.challenge_id,
    template=pack.template,
    seed=pack.seed,
    passed=1,
    total=1,
    runner_version="runner-v1",
    signing_key="replace-me",
).token

payload = verify_attestation(token, signing_key="replace-me")
assert payload is not None
```

## Judge runner notes

`judge_submission()` expects Docker to be available and daemon reachable.
The package includes runner assets under `moltcha_core/runner_assets/` and can build the image on first use.

## Tests

```bash
pytest -q
```

## License

MIT
