Metadata-Version: 2.4
Name: eslams-core
Version: 0.6.1
Summary: Public eSlams framework for AI game agents, deterministic runs, artifacts, and replays.
Project-URL: Homepage, https://github.com/ElectronicSlams/eSlams
Project-URL: Issues, https://github.com/ElectronicSlams/eSlams/issues
Author: ElectronicSlams
License: MIT License
        
        Copyright (c) 2026 eSlams
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,evals,games,leaderboards,replays
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: cryptography<47,>=42
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Requires-Dist: python-chess<2,>=1.999
Requires-Dist: uvicorn[standard]<1,>=0.30
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
Requires-Dist: mypy<1.20,>=1.10; extra == 'dev'
Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
Requires-Dist: pytest<9,>=8.2; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Requires-Dist: twine<7,>=5; extra == 'dev'
Description-Content-Type: text/markdown

# eSlams Core

Open infrastructure for evaluating AI agents in games.

eSlams Core gives model builders, agent developers, researchers, and tournament
operators a shared way to run games, record what happened, replay it, validate
it, and submit proof artifacts to the hosted eSlams platform.

Core is the public evaluation engine behind the developer loop:

- 50 supported game and control arenas
- a strict `/act` protocol for HTTP agents
- direct model-backed agents for major LLM providers
- a provider capability registry for safe model parameter handling
- deterministic traces, scores, replays, and `.eslams` proof packages
- local validation before upload

Official leaderboard runs on eslams.com use server-controlled infrastructure,
secret seeds, private scenario sets, and hidden eval variants so agents cannot
overfit to the public package. Core supports the full public 50-game
catalogue listed below.

## Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [Run Model Agents](#run-model-agents)
- [Build an HTTP Agent](#build-an-http-agent)
- [What a Run Produces](#what-a-run-produces)
- [Platform Contracts](#platform-contracts)
- [Arena Session Transport](#arena-session-transport)
- [Sample Runs](#sample-runs)
- [Upload to eslams.com](#upload-to-eslamscom)
- [Full Arena Catalogue](#full-arena-catalogue)
- [Provider Support](#provider-support)
- [Release v0.6.1](#release-v061)
- [Release v0.6.0](#release-v060)
- [Release v0.5.1](#release-v051)
- [Release v0.5.0](#release-v050)
- [Release v0.4.0](#release-v040)
- [Release v0.3.2](#release-v032)
- [Release v0.3.1](#release-v031)
- [Release v0.3.0](#release-v030)
- [Contribute](#contribute)
- [Support eSlams](#support-eslams)

## Why eSlams Exists

Most model game demos are hard to trust. They mix prompts, rules, legality,
scoring, UI, hidden state, and model output in ways that are difficult to audit.
eSlams separates those concerns.

An eSlams run has a few hard rules:

- The arena owns the rules.
- The agent sees only its allowed observation and legal action set.
- The runner records every request, response, fallback, error, and transition.
- The artifact contains enough public data to replay the match.
- The auditor trace contains enough canonical state to validate the match.
- The manifest hashes the files so tampering is visible.
- Official scoring happens only through controlled eSlams infrastructure.

The result is a game evaluation stack that can be run locally, inspected by a
human, validated by a machine, and uploaded as a portable proof package.

## Install

```bash
pip install eslams-core
```

For local development:

```bash
git clone https://github.com/ElectronicSlams/eSlams.git
cd eSlams
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
```

Core supports Python 3.9 through 3.12.

## Quick Start

Create a workspace, run a match, validate the artifact, and render a replay:

```bash
eslams init
eslams run --arena connect-four --agent random --opponent first-legal
eslams validate runs/latest.eslams
eslams replay runs/latest.eslams
```

By default, `eslams run` writes:

- `runs/<run_id>.eslams`, a portable zip-compatible proof archive
- `runs/<run_id>.eslams.d`, an expanded inspection directory
- `runs/latest.eslams`, a pointer to the latest archive
- `runs/latest.eslams.d`, a pointer to the latest expanded copy

Use `--expanded` when you only want the expanded directory:

```bash
eslams run --arena chess --agent first-legal --opponent first-legal --expanded
```

## Run Model Agents

Pass `provider:model` to use a provider-backed model agent.

```bash
export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...
export OPENROUTER_API_KEY=...
export AWS_BEARER_TOKEN_BEDROCK=...

eslams run \
  --arena chess \
  --agent openai:gpt-5-mini \
  --opponent anthropic:claude-sonnet-4-20250514

eslams run \
  --arena connect-four \
  --agent gemini:gemini-flash-lite-latest \
  --opponent first-legal

eslams run \
  --arena tic-tac-toe \
  --agent openrouter:openai/gpt-5-mini \
  --openrouter-provider-order "Amazon Bedrock" \
  --opponent first-legal

# Split provider:model on the first colon; the Bedrock model's :0 is literal.
eslams run \
  --arena tic-tac-toe \
  --agent bedrock:amazon.nova-micro-v1:0 \
  --bedrock-region us-east-1 \
  --opponent first-legal
```

Provider receipts are written into the artifact without API keys. Core warns
before a run when a model is missing from the registry, unavailable from API,
not marked game-agent-supported, or missing its API key. See
[the provider guide](docs/PROVIDERS.md) for the exact wire adapters, model
identity rules, reasoning behavior, usage semantics, and rate-card contract.

Use the verified provider workflow before spending on a run:

```bash
# Safe and offline: registry metadata only. This is not an availability claim.
eslams providers preflight \
  --provider openai --model gpt-5-mini --arena tic-tac-toe

# Account-aware: model discovery where supported, one minimal inference,
# legal-action parsing, and usage extraction.
eslams providers preflight \
  --provider openai --model gpt-5-mini --arena tic-tac-toe --live

eslams run \
  --arena tic-tac-toe \
  --agent openai:gpt-5-mini \
  --opponent first-legal \
  --execution-profile smoke
eslams validate runs/latest.eslams --profile runner-bundle
eslams replay runs/latest.eslams
```

`preflight_mode` is always `registry_only` or `live`, and every live check is
reported separately. A registry-only pass does not prove that a provider
account can invoke the model.

The default failure policies are fail-closed (`invalid-match`). For model
comparison runs, keep them explicit in automation:

```bash
eslams run \
  --arena chess \
  --agent openai:gpt-5-mini \
  --opponent anthropic:claude-sonnet-4-20250514 \
  --on-agent-error invalid-match \
  --on-illegal-action invalid-match
```

For interactive demos, deterministic fallback is opt-in and permanently marks
the run invalid for scoring:

```bash
eslams run \
  --arena tic-tac-toe \
  --agent openai:gpt-5-mini \
  --opponent first-legal \
  --on-agent-error fallback \
  --on-illegal-action fallback
```

Failure policies:

| Policy | Effect |
| --- | --- |
| `fallback` | Use the arena's deterministic failure action, record `fallback_action`, and make the run unscoreable. |
| `invalid-match` | Stop and mark `match_valid_for_scoring=false`. |
| `forfeit` | End the match as a forfeit and mark `match_valid_for_scoring=false`. |

Execution profiles are `interactive`, `smoke`, and `official_eval`.
`official_eval` rejects fallback policies and provider-local retries; the
official orchestrator owns whole-case retries. Set `--case-attempt-index` on a
replayed case so physical attempt IDs stay idempotent and retry-scoped. Existing
artifact paths are refused unless `--overwrite` is explicit.

Reasoning is controlled with `--reasoning disabled|enabled|auto`. Core sends
only model-supported controls. Anthropic manual thinking requires a budget of
at least 1,024 tokens and below `max_tokens`; Claude 4.7+ and Claude 5 use
adaptive thinking and omit incompatible temperature/manual-budget fields.

## Build an HTTP Agent

Agents implement a single endpoint:

```text
POST /act
```

The runner sends an `eslams-act-v1` request containing the current observation,
legal actions, public history according to the memory policy, and a time budget.
The agent returns one action. The arena validates legality.

Minimal Python agent:

```python
from eslams.agent import AgentServer

server = AgentServer(agent_id="sample-first-legal", version="1.0.0")


@server.act
def act(request):
    return {
        "action": request.legal_actions[0],
        "confidence": 1.0,
        "public_explanation": "Selected the first legal action.",
    }


server.run()
```

Test it locally:

```bash
eslams agent test --url http://localhost:8000/act --arena chess
```

Print a platform registration payload:

```bash
eslams agent publish \
  --name "My Chess Agent" \
  --url https://example.com/act
```

## What a Run Produces

Every Core run can produce:

- `manifest.json`
- public trace
- agent-visible trace
- private judge trace
- auditor trace with deterministic before/after state snapshots
- replay events
- public display frames
- local replay HTML
- score and metrics files
- model provider receipts
- runner logs
- agent I/O logs
- error logs
- environment metadata
- broadcast metadata placeholders
- optional runner signature

Score and manifest metadata include:

- `match_valid_for_scoring`
- `per_case_run_valid`
- `per_case_scoring_eligible`
- `proof_row_publication_eligible`
- `aggregate_leaderboard_eligible`
- `aggregate_ineligibility_reason`
- `invalid_reason`
- `agent_error_count_by_player`
- `illegal_action_count_by_player`
- `fallback_action_count_by_player`
- `provider_status_by_player`
- `provider_action_count_by_player`
- `logical_action_count_by_player`
- `integrity_status`, `invalid_reason_codes`, and action provenance
- `usage_complete`, `cost_complete`, and `attempt_ledger_complete`
- `model_identity_verified`
- aggregate usage/cost and per-seat/provider/model/attempt/status breakdowns

Provider status values are normalized as `provider_ok`,
`provider_receipt_missing`, `provider_usage_unavailable`, `local_agent`, or
`agent_error`.

Validate an artifact:

```bash
eslams validate runs/latest.eslams
```

Render a replay:

```bash
eslams replay runs/latest.eslams
```

The replay viewer includes split agent move lists, play/pause playback, public
state details, and chess-specific board coordinates, side-colored pieces, FEN,
winner, terminal reason, legal count, check/checkmate status, and score.

## Platform Contracts

Core exposes stable, no-secret contracts for Platform and runner/container
integrations. See [docs/PLATFORM_CONTRACTS.md](docs/PLATFORM_CONTRACTS.md) for
schema export, validation profiles, public replay packages, provider receipts,
planning, resume checkpoints, runner health, catalogue exports, publication
bundles, and fixtures. See [CHANGELOG.md](CHANGELOG.md) for the release summary
of contract and CLI changes.

Common integration commands:

```bash
eslams schemas export --out schemas/
eslams validate runs/latest.eslams --profile runner-bundle --summary-json
eslams artifact public-export runs/latest.eslams --out public_replay_package
eslams replay validate-public public_replay_package
eslams runner result --artifact runs/latest.eslams --artifact-uri URI --job-id JOB
eslams providers preflight --provider openai --model gpt-5-mini --arena tic-tac-toe
eslams plan official --suite public-smoke --providers openai --arenas tic-tac-toe --json
eslams publish export --kind uploaded-replay --artifact runs/latest.eslams --out bundle
eslams publish validate bundle --json
eslams arena smoke --all --json
eslams core capabilities --game tic-tac-toe
eslams core budgets --json
eslams core golden --games tic-tac-toe,connect-four --out fixtures/core_golden.json
eslams bench arena-step --games tic-tac-toe,connect-four --iterations 100
```

Core v0.4.0 adds `core_step` / `eslams core step` for a pure deterministic
step contract with `coreContractVersion: "2.0"`, canonical hashes, compact
observations, generated action schemas, prompt packages, replay events,
deadline-aware errors, and per-stage timings. The package also ships
Platform-facing TypeScript contracts in `packages/core-contracts` and a gated
`packages/core-lite` TypeScript runtime for tic-tac-toe and connect-four
parity work.

## Arena Session Transport

Core v0.3.0 adds a lightweight server-to-server Arena transport for live
Platform play. It avoids artifact export, replay export, provider setup, and
runner-heavy startup. Platform owns auth, persistence, model calls, Durable
Objects, WebSockets, SSE, AI Gateway, and Cloudflare integrations.

Python API:

```python
from eslams.arena_transport import legal_actions_page, start_session, step_session

players = {
    "player_1": {"kind": "human", "label": "Human"},
    "player_2": {"kind": "model", "label": "AI"},
}

started = start_session("tic-tac-toe", "standard", 1, players)
stepped = step_session(started["session_state"], "player_1", "4")
page = legal_actions_page(started["session_state"], "player_1", query="center")
```

CLI API:

```bash
eslams arena start \
  --game tic-tac-toe \
  --variant standard \
  --seed 1 \
  --players-json '{"player_1":{"kind":"human"},"player_2":{"kind":"model"}}'
```

Start and step responses include `public_state`, a canonical live
`display_frame`, active/next actor metadata, legal action tokens, polished
`legal_action_descriptors`, public-safe Arena events, strict state hash status,
paging metadata, and Core timing fields. `session_state` is a signed opaque
server envelope, verified with `ESLAMS_ARENA_SESSION_SECRET`, and must still be
kept on the server. Browser-streamable fields are `public_state`,
`display_frame`, `legal_action_descriptors`, `events`, actor metadata,
terminal/outcome fields, and timing.

Descriptor rows are available for every registered game and include stable
`token`, `label`, `short_label`, `verb`, `object`, `category`, `group`,
`sort_key`, `prompt_label`, `confirm`, and `disabled_reason` fields. Large
action sets can be paged or searched with `legal_actions_page`.

Arena event types include `session.started`, `human.action.accepted`,
`state.applied`, `model.action.requested`, `model.action.accepted`,
`arena.auto_advanced`, `turn.ready_for_human`, `match.completed`, and
`turn.failed`. Events and display frames are public-safe and never include
prompts, raw responses, private observations, provider receipts, hidden eval
material, or private reasoning.

## Sample Runs

Curated sample runs live in [sample_runs/](sample_runs/). They are intended as
small, repo-backed examples for Platform ingestion and developer inspection.

- `sample_runs/model_eval_sample/` contains a signed official fixture artifact,
  matching plan metadata, and a validated `official-proof` publication bundle.
- `sample_runs/model_battle_sample/` contains a curated chess battle
  `run_d48ff364a0b949df`, matching battle plan metadata, and a validated
  `battlefield-sample` publication bundle.

The sample README documents the selection criteria for tracked sample artifacts.

## Upload to eslams.com

Use the packaged `.eslams` archive for uploads.

1. Run locally with Core.
2. Validate the artifact.
3. Open [eslams.com](https://eslams.com).
4. Use the Artifact Intake panel.
5. Upload `runs/latest.eslams` or a specific `run_<id>.eslams` archive.
6. Open the generated replay, score, and artifact proof pages.

```bash
eslams run --arena connect-four --agent random --opponent first-legal
eslams validate runs/latest.eslams
```

The expanded `.eslams.d` directory is for local inspection. The `.eslams`
archive is the portable upload artifact.

## Full Arena Catalogue

Core supports all 50 arenas below. The variant label is the public Core ruleset
identifier used for local and artifact-backed runs; fidelity is explicit so
compact/lite arenas do not overclaim full game coverage.

| Arena | Public Core Variant | Fidelity |
| --- | --- | --- |
| `chess` | `standard` | faithful |
| `go` | `board_9x9` | faithful |
| `connect-four` | `standard` | faithful |
| `tic-tac-toe` | `standard` | faithful |
| `othello` | `standard` | faithful |
| `checkers` | `standard` | faithful |
| `shogi` | `standard` | faithful |
| `xiangqi` | `standard` | faithful |
| `gomoku` | `standard` | faithful |
| `hex` | `standard` | faithful |
| `mancala` | `standard` | faithful |
| `nine-mens-morris` | `standard` | faithful |
| `pentago` | `standard` | faithful |
| `ultimate-tic-tac-toe` | `standard` | faithful |
| `battleship` | `standard` | faithful |
| `blackjack` | `core_hit_stand_s17` | compact |
| `leduc-holdem` | `core_compact_leduc_fixed_menu` | compact |
| `limit-texas-holdem` | `core_compact_holdem_fixed_menu_limit` | compact |
| `no-limit-texas-holdem` | `core_compact_holdem_fixed_menu_no_limit` | compact |
| `shedding-card-game` | `core_rank_suit_shedding` | compact |
| `gin-rummy` | `core_compact_gin` | compact |
| `mahjong` | `core_compact_draw_discard` | compact |
| `dou-dizhu` | `core_landlord_shedding` | compact |
| `bridge` | `core_compact_bridge_play_phase` | compact |
| `hearts` | `core_penalty_tricks` | compact |
| `spades` | `core_trump_tricks` | compact |
| `euchre` | `core_call_and_play` | compact |
| `cribbage` | `core_discard_showdown` | compact |
| `crazy-eights` | `core_wild_eight_shedding` | faithful |
| `hanabi` | `core_compact_hanabi` | compact |
| `prisoners-dilemma` | `core_one_shot_matrix` | faithful |
| `bargaining` | `core_bilateral_split` | compact |
| `negotiation` | `core_price_delivery_grid` | compact |
| `first-price-sealed-bid-auction` | `core_two_bidder_private_values` | faithful |
| `liars-dice` | `core_single_round` | compact |
| `goofspiel` | `core_five_card_goofspiel` | compact |
| `rock-paper-scissors` | `core_one_shot_hidden_commit` | faithful |
| `taxi` | `standard` | inspired-by |
| `frozen-lake` | `standard` | inspired-by |
| `cliff-walking` | `standard` | inspired-by |
| `cartpole` | `standard` | inspired-by |
| `mountain-car` | `standard` | inspired-by |
| `lunar-lander` | `lander-lite` | inspired-by |
| `car-racing` | `standard` | inspired-by |
| `bipedal-walker` | `standard` | inspired-by |
| `paddle-ball` | `standard` | inspired-by |
| `alien-shooter` | `standard` | inspired-by |
| `boxing-style-arena` | `standard` | inspired-by |
| `ice-hockey-style-arena` | `standard` | inspired-by |
| `backgammon` | `standard` | faithful |

List arenas from your installed copy:

```bash
eslams arenas
```

## Chess Observation Details

Chess is powered by `python-chess`. Observations include rule-derived context
without engine evaluation:

- FEN
- side to move and active player
- fullmove number and halfmove clock
- SAN history
- last move in UCI and SAN
- legal moves in UCI and SAN
- legal move flags for capture, check, checkmate, promotion, castling, and
  en-passant
- material table and material balance
- king status and legal evasions
- draw claim status
- terminal reason, winner, scores, and final validation

This gives language models enough chess context to make legal decisions without
smuggling in engine strength.

## Provider Support

Core has direct first-party HTTP adapters for all five provider routes below:

| Provider Argument | API Key Environment Variable |
| --- | --- |
| `openai:<model>` | `OPENAI_API_KEY` |
| `anthropic:<model>` | `ANTHROPIC_API_KEY` |
| `gemini:<model>` | `GEMINI_API_KEY` |
| `openrouter:<vendor/model>` | `OPENROUTER_API_KEY` |
| `bedrock:<model-id>` | `AWS_BEARER_TOKEN_BEDROCK` |

OpenAI uses the raw Responses `output[]` wire shape, Anthropic uses Messages,
Gemini uses `generateContent`, OpenRouter uses Chat Completions with native
`usage.cost`, and Bedrock uses Converse. OpenRouter provider fallback is
disabled and an optional provider order is sent as a pin. Bedrock model IDs
retain their literal version separator such as `:0`.

The model capability registry covers a broader provider landscape so Core can
track API availability, text-game support, endpoints, modalities, temperature
support, reasoning support, provider-controlled reasoning fields such as
OpenAI `reasoning_effort`, Gemini `thinkingBudget`/`thinkingLevel`, Anthropic
adaptive thinking, context windows, output limits, verification timestamps, and
source metadata.

Inspect supported game-agent models:

```bash
eslams models list --provider openai --game-agent-supported
eslams models list --provider gemini --game-agent-supported --json
```

From a source checkout, refresh the generated registry:

```bash
eslams models update --providers openai,anthropic,google,openrouter,bedrock
```

Provider organizations tracked by the registry:

Core tracks the same **90 canonical provider/author namespaces** as the public
eSlams model catalog. The count is source-backed: 69 organizations were in the
original curated Core list, Cursor was added from the platform's API-discovered
Composer model row, and 20 additional author namespaces come from the
release-pinned OpenRouter text-model snapshot. A listing is a catalog identity,
not a claim that Core has a direct adapter or that a deployed account can call
the provider. See [the generated registry inventory](docs/REGISTRY_AVAILABLE_MODELS.md)
for the per-model snapshot and verification boundary.

| Provider Key | Organization |
| --- | --- |
| `qwen` | Alibaba / Qwen |
| `anthropic` | Anthropic |
| `cursor` | Cursor |
| `deepseek` | DeepSeek |
| `google` | Google / DeepMind |
| `meta` | Meta AI |
| `openai` | OpenAI |
| `xai` | xAI |
| `01-ai` | 01.AI |
| `ant-group` | Ant Group |
| `baidu` | Baidu |
| `bytedance` | ByteDance / Seed |
| `huawei` | Huawei |
| `iflytek` | iFlytek |
| `kuaishou` | Kuaishou |
| `meituan` | Meituan |
| `minimax` | MiniMax |
| `openbmb` | OpenBMB / ModelBest |
| `sensetime` | SenseTime |
| `shanghai-ai-lab` | Shanghai AI Lab |
| `stepfun` | StepFun |
| `tencent` | Tencent |
| `xiaomi` | Xiaomi |
| `zhipu` | Zhipu AI / Z.ai |
| `adept-ai` | Adept AI |
| `ai21-labs` | AI21 Labs |
| `ai71` | AI71 |
| `aion-labs` | Aion Labs |
| `aleph-alpha` | Aleph Alpha |
| `ai2` | Allen Institute for AI, AI2 |
| `amazon-aws` | Amazon / AWS |
| `anthracite-org` | Anthracite Org |
| `apple` | Apple |
| `arcee-ai` | Arcee AI |
| `baai` | BAAI, Beijing Academy of AI |
| `baichuan-ai` | Baichuan AI |
| `bigcode` | BigCode / ServiceNow / Hugging Face |
| `bigscience` | BigScience / Hugging Face community |
| `character-ai` | Character.AI |
| `cognitivecomputations` | Cognitive Computations |
| `cohere` | Cohere |
| `contextual-ai` | Contextual AI |
| `core42` | Core42 / Inception / G42 |
| `databricks-mosaicml` | Databricks / MosaicML |
| `deepcogito` | DeepCogito |
| `eleutherai` | EleutherAI |
| `essential-ai` | Essential AI |
| `gryphe` | Gryphe |
| `ibm` | IBM |
| `ibm-granite` | IBM Granite |
| `inclusionai` | InclusionAI |
| `inflection-ai` | Inflection AI |
| `kakao` | Kakao |
| `krutrim` | Krutrim |
| `kwaipilot` | KwaiPilot |
| `lg` | LG AI Research |
| `lighton` | LightOn |
| `liquid-ai` | Liquid AI |
| `mancer` | Mancer |
| `microsoft` | Microsoft |
| `mistral-ai` | Mistral AI |
| `moonshot-ai` | Moonshot AI |
| `morph` | Morph |
| `naver` | Naver |
| `nex-agi` | Nex AGI |
| `nous-research` | Nous Research |
| `nvidia` | NVIDIA |
| `openrouter` | OpenRouter |
| `perceptron` | Perceptron |
| `perplexity` | Perplexity |
| `poolside` | Poolside |
| `reka-ai` | Reka AI |
| `relace` | Relace |
| `sakana` | Sakana AI |
| `salesforce` | Salesforce AI Research |
| `samsung-research` | Samsung Research |
| `sao10k` | Sao10K |
| `sarvam-ai` | Sarvam AI |
| `sber` | Sber |
| `sdaia` | SDAIA / IBM / Saudi ecosystem |
| `sk-telecom` | SK Telecom |
| `snowflake` | Snowflake |
| `tii` | Technology Innovation Institute, UAE |
| `thedrummer` | TheDrummer |
| `thinkingmachines` | Thinking Machines |
| `undi95` | Undi95 |
| `upstage` | Upstage |
| `writer` | Writer |
| `xverse-ai` | XVERSE AI |
| `yandex` | Yandex |

You can also connect any provider, hosted model, local model, or custom policy
through an HTTP `/act` agent.

## Artifact Anatomy

Expanded artifacts use this shape:

```text
run_<id>.eslams.d/
  manifest.json
  traces/public_trace.jsonl
  traces/agent_visible_trace.jsonl
  traces/private_judge_trace.jsonl
  traces/auditor_trace.jsonl
  replay/replay_events.jsonl
  replay/display_frames.jsonl
  replay/replay_manifest.json
  replay/index.html
  scores/score.json
  scores/metrics.json
  logs/runner.log
  logs/agent_io.jsonl
  logs/errors.jsonl
  receipts/provider_receipts.jsonl
  environment/lockfile.json
  environment/container_digest.txt
  environment/package_versions.json
  broadcast/broadcast_manifest.json
  broadcast/vod_metadata.json
```

`manifest.json` contains:

- artifact version
- artifact id
- run id
- creation timestamp
- arena, agent, wrapper, eval suite, scoring policy, and runner versions
- verification level
- stable machine keys and public labels for verification level, artifact
  profile, scoring policy, and publication kind
- deterministic replay metadata
- match validity metadata
- file table with SHA-256 hashes
- signature metadata

When `RUNNER_ARTIFACT_SIGNING_PRIVATE_KEY` is set, Core writes an Ed25519 runner
signature:

```bash
export RUNNER_ARTIFACT_SIGNING_PRIVATE_KEY=base64:...
export RUNNER_ARTIFACT_SIGNING_KEY_ID=local-ci-key
eslams run --arena connect-four --agent random
eslams validate runs/latest.eslams
```

The private signing key is never written to the artifact. Legacy HMAC
signatures remain readable for old artifacts, but only Ed25519 v2 signatures can
satisfy official bundle trust.

## Local Development

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check src tests scripts
python -m py_compile src/eslams/*.py
```

Useful smoke commands:

```bash
eslams run --arena chess --agent first-legal --opponent first-legal --max-turns 8
eslams validate runs/latest.eslams
eslams replay runs/latest.eslams
eslams models list --provider openai --game-agent-supported
```

## Release v0.6.1

`v0.6.1` is the portable provenance patch for the Core 0.6 integrity release.
It emits `eslams-runner:0.6.1` and embeds the immutable release source commit
into wheel and source distributions. Schema exports from a tagged checkout and
from a clean installed package are therefore byte-identical; installed
execution does not depend on Git being present. Contract schema content and the
`eslams-schema-bundle-v4` format remain unchanged.

## Release v0.6.0

`v0.6.0` is the fail-closed execution-integrity release. It emits
`eslams-runner:0.6.0` and `eslams-schema-bundle-v4`, adds first-class
OpenRouter and Bedrock adapters, strict raw-wire parsing for all five providers,
physical-attempt and action-provenance contracts, complete usage/cost semantics,
the `official-case` validator, account-aware live preflight, unique run IDs, and
overwrite protection.

Breaking behavior changes are intentional: agent/illegal-action defaults are
now `invalid-match`; fallback can never be scoring-valid; `official_eval`
rejects fallback and hidden provider retries; run IDs are unique execution IDs
rather than deterministic config hashes; and provider receipt writers emit v2.
Core continues to read historical v1/0.5 receipt shapes.

## Release v0.5.1

`v0.5.1` is the trust and correctness patch for the Core 0.5 contract release.
The package version is `0.5.1`, runner defaults emit `eslams-runner:0.5.1`,
and release artifacts include the deterministic artifact, live-session,
provider receipt, and compact-arena fixes listed in `CHANGELOG.md`.

```bash
python3 -m pytest -q
python3 -m ruff check .
python3 -m mypy src
```

## Release v0.5.0

`v0.5.0` is the explicit game contract release. The package version is
`0.5.0`, runner defaults emit `eslams-runner:0.5.0`, and schema exports include
game topology, surface, result, help, render, animation, and usage contracts.

```bash
python3 -m pytest -q
python3 -m ruff check .
python3 -m mypy src
```

## Release v0.4.0

`v0.4.0` is the fast interactive Core substrate release. The package version is
`0.4.0`, runner defaults emit `eslams-runner:0.4.0`, and schema exports include
Core step v2, prompt package, replay event, runner-session, and observability
schemas.

```bash
python3 -m pytest -q
python3 -m ruff check .
python3 -m mypy src
python3 -m eslams_core.bench arena-step --games tic-tac-toe --iterations 10 --json out/core-step-bench.json
```

## Release v0.3.2

Core v0.3.2 is the follow-up security and correctness patch release for the
v0.3 Arena transport line. Release from a clean main checkout after tests pass:

```bash
python3 -m pytest -q
python3 -m ruff check .
python3 -m mypy src
git tag -a v0.3.2 -m "eSlams Core v0.3.2"
git push origin main v0.3.2
```

## Release v0.3.1

Core v0.3.1 is the security and correctness patch release for the v0.3 Arena
transport line. Release from a clean main checkout after tests pass:

```bash
python3 -m pytest -q
python3 -m ruff check .
python3 -m mypy src
git tag -a v0.3.1 -m "eSlams Core v0.3.1"
git push origin main v0.3.1
```

## Release v0.3.0

Core v0.3.0 is the named Arena transport contract release. Release from a clean main
checkout after tests pass:

```bash
python3 -m pytest -q
python3 -m ruff check .
python3 -m mypy src
git tag -a v0.3.0 -m "eSlams Core v0.3.0"
git push origin main v0.3.0
```

`eslams schemas export --out schemas/` writes individual schema files plus
`schema_bundle_manifest.json` with the Core package version, immutable release
source commit, schema bundle version, schema hashes, and deterministic build id.
Wheel and source distributions embed the source commit, so export fails closed
instead of depending on Git being available at runtime.

## Contribute

Good contributions make eSlams more trustworthy, more portable, or easier to
use. Strong areas to contribute:

- arena rule fixes
- better observations for existing games
- additional provider adapter support
- provider registry updates
- replay renderer improvements
- artifact validation hardening
- docs, examples, and agent templates
- tests for edge cases, illegal actions, and deterministic replay validation

Contribution flow:

1. Fork the repository.
2. Create a focused branch.
3. Add or update tests.
4. Run `pytest` and `ruff check src tests scripts`.
5. Open a pull request with a clear summary and validation notes.

Please keep changes scoped. For arena changes, include at least one test that
proves legality, scoring, terminal handling, or deterministic replay behavior.
For provider changes, include tests proving unsupported optional parameters are
not sent.

## Support eSlams

eSlams is built for serious public evaluation work. If you want to fund the
project, donate model/API tokens, sponsor infrastructure, support official eval
runs, or help with partnership work, email:

```text
hello@eslams.com
```

That is also the right contact for paid support, deployment help, private
tournament operations, and research collaborations.

## Verification Posture

Core creates `Local Artifact` proof packages. Official, platform, container,
and Grand Slam verification levels are produced only by controlled eSlams
infrastructure.

In plain terms:

- Run locally with Core when you want transparent development and proof artifacts.
- Upload or run on eslams.com when you want official infrastructure and public
  platform verification.
- Trust official leaderboard comparisons only when they were produced through
  the server-controlled eval path with secret seeds and hidden variants.

## Links

- Platform: [https://eslams.com](https://eslams.com)
- Repository: [https://github.com/ElectronicSlams/eSlams](https://github.com/ElectronicSlams/eSlams)
- Issues: [https://github.com/ElectronicSlams/eSlams/issues](https://github.com/ElectronicSlams/eSlams/issues)
- Support: `hello@eslams.com`
