pyattacker 0.1.0__tar.gz

pyattacker-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The two versions declared in pyproject.toml classifiers.
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Test
+        # The whole suite is offline; network access is never needed.
+        run: uv run pytest
+
+      - name: CLI smoke test
+        run: uv run pyattacker demo --pipelines 25 --store runs/demo.db
+
+      - name: Example smoke tests
+        # The examples are documentation, and documentation rots: the llm_eval demo also asserts
+        # its own claim about checkpoint granularity, so this catches recovery regressions.
+        run: |
+          uv run python examples/quickstart.py
+          uv run python examples/sharded.py
+          uv run python -m examples.llm_eval.demo
+
+      - name: Build sdist and wheel
+        run: uv build

pyattacker-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.uv-cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+runs/
+*.db
+*.db-wal
+*.db-shm
+.pyattacker/
+
+.scratch/

pyattacker-0.1.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-09-17
+
+First release. An artifact-centric async orchestration kernel: it runs many independent pipelines to
+completion, resumably and observably, without touching the network itself.
+
+### Core
+
+* **Five-concept kernel** — artifact, task, pipeline, resource, algorithm. A task is a unary
+  `(artifact) -> artifact` function, sync or async; a pipeline is a linear chain of them and the unit of
+  completion; pipelines share nothing but resource pools.
+* **Task-level checkpoints.** Every artifact is persisted the moment it is produced, so `resume` restarts at
+  the first task that produced nothing and re-sends nothing that already succeeded. The seed artifact is
+  persisted too, so recovery does not depend on the original dataset file.
+* **Content-addressed identity.** `pipeline_key` is a digest of the task-chain fingerprint, the seed, and the
+  repeat index, which makes reruns idempotent, results reproducible, and `map(seeds, repeats=k)` (pass@k) free.
+  Task source digests are included, so changing task code is treated as a new pipeline rather than reusing a
+  stale checkpoint.
+* **Lease safety contract.** Resources are only usable through a lease, and a task never holds one after it
+  ends: `async with ctx.acquire(...)` returns on exit, on exception, on cancellation and on timeout, and the
+  escape hatch is force-reclaimed with a `lease.leaked` event. Reclaim is a pure synchronous function, so
+  `CancelledError` cannot interrupt it. `strict_leases=True` turns a leak into a task failure.
+* **Resource pools** with per-resource capacity, a `READY/DEGRADED/DEAD/REVOKED` state machine driven by
+  explicit `lease.report(...)`, quota accounting, publish/subscribe, and a signal bus.
+* **Seven acquisition algorithms** — `wait`, `backoff`, `least_busy`, `failover`, `sticky`, `quota_aware`,
+  `immediate` — kept orthogonal to retry policy: the algorithm decides how to *get* a resource, retry decides
+  what to do *after* a failure.
+* **Failure classification and retry.** `error_class_of` is a pure function mapping status codes and exception
+  types to `timeout`/`rate_limit`/`upstream`/`fatal`/`connection`/`invalid`/`unknown`; `Retrying` adds
+  exponential backoff with full jitter and a total-time budget. No retry by default. **Every retry decision is
+  persisted** — `{retry, reason, delay_s, error_class, attempt, max_attempts, retry_after}`.
+
+### Scheduling and persistence
+
+* **Backoff parks the pipeline instead of sleeping in a worker**, so `concurrency` means attempts in flight.
+  A parked pipeline is never mistaken for a dead one: the run waits for it, and a stop records it as resumable.
+* **Targeted pool wakeups** — releasing a resource wakes only the waiters whose selector can use it.
+* **Write-behind batching** for append-only facts (attempts, events), while state writes — pipelines, tasks,
+  artifacts — always go straight through. `SIGKILL` can cost the last batch of history, never a checkpoint.
+  `--no-write-behind` opts out.
+* **SQLite store** (WAL, `synchronous=NORMAL`) across seven tables plus an in-memory store with identical
+  semantics. WAL's one-writer-many-readers model is what lets `watch`/`report`/`serve` run beside a live run.
+* **Wait-time metrics** — `waits_total`, `wait_ms_avg`, `p50`, `p95`, `max`, and an `acquire.slow_wait` event
+  past `slow_wait_ms`. Suspected deadlocks emit `acquire.suspected_deadlock`.
+
+### Scale, I/O and ecosystem
+
+* **Deterministic sharding** — `--shard I/N` for one process doing its share, `--shards N` to spawn children
+  locally. Assignment is a pure function of the pipeline key, so the split is stable and resume-safe.
+* **Merged reports** across shard stores: de-duplicated by `pipeline_id`, statistics recomputed, folded row
+  count reported.
+* **Export** in five row shapes (`pipelines`, `tasks`, `attempts`, `events`, `artifacts`) and three formats
+  (`jsonl`, `json`, `csv`, with an `extra` column for late keys).
+* **Entry-point plugins** for tasks, algorithms, codecs and stores. Built-ins resolve first, and a plugin that
+  raises on import is recorded rather than fatal — `pyattacker plugins` shows both.
+* **Artifact backends** — `inline` (default), content-addressed `file://` spilling above a threshold with
+  transparent hydration on read, and `null`.
+* **`fanout(...)`** for genuine branching inside one task, with group-level retry granularity as the stated price.
+* **Read-only HTTP endpoint** — `pyattacker serve`, a dependency-free dashboard plus JSON. Loopback-only and
+  unauthenticated by design; it is a debug view, not a service.
+* **CLI** — `run`, `resume`, `report`, `watch`, `export`, `serve`, `plugins`, `validate`, `demo`, with exit
+  codes `0`/`1`/`2`/`130`.
+* **Declarative layer** — YAML/TOML/JSON describing composition and resources, with `${ENV}` expansion and
+  `--strict-env`.
+
+### Documentation and testing
+
+* A fourteen-step [tutorial](docs/tutorial.md) whose every code block is extracted and executed by the test
+  suite, so documentation that rots fails CI.
+* A [design document](docs/design.md) stating the six invariants, the lease contract, the data model, and
+  twelve known tradeoffs up front.
+* A [CLI reference](docs/cli.md) and four worked examples, including one that *measures* the checkpoint
+  granularity tradeoff rather than asserting it.
+* The suite is offline and deterministic — all time goes through an injectable `Clock` — and runs in seconds.
+  CI covers Python 3.11 and 3.12, lint, the examples, and a build.
+
+### Known limitations
+
+Deliberate, and documented in [`docs/design.md`](docs/design.md) §8: stop conditions are best-effort;
+write-behind can lose the tail of history (never a checkpoint); `journal=summary` and the `null` backend trade
+away recovery granularity; resource health relies on explicit reporting; `quota_aware` is a preference, not a
+hard limit; asyncio tasks only (wrap blocking code with `asyncio.to_thread`); one writer per database; shard
+balance is statistical; a merged report is a union, not a sum; a pipeline is a linear chain; the HTTP endpoint
+is unauthenticated.
+
+[0.1.0]: https://github.com/Hazer-BJTU/pyattacker/releases/tag/v0.1.0

pyattacker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pyattacker contributors
+
+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.

pyattacker-0.1.0/PKG-INFO

@@ -0,0 +1,347 @@
+Metadata-Version: 2.5
+Name: pyattacker
+Version: 0.1.0
+Summary: Artifact-centric, resumable async task orchestration: pipeline / task / resource pool.
+Project-URL: Homepage, https://github.com/Hazer-BJTU/pyattacker
+Project-URL: Repository, https://github.com/Hazer-BJTU/pyattacker
+Project-URL: Issues, https://github.com/Hazer-BJTU/pyattacker/issues
+Project-URL: Changelog, https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md
+Project-URL: Design, https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md
+Author: pyattacker contributors
+License: MIT
+License-File: LICENSE
+Keywords: artifact,async,evaluation,orchestration,pipeline,resource-pool
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# pyattacker
+
+[![CI](https://github.com/Hazer-BJTU/pyattacker/actions/workflows/ci.yml/badge.svg)](https://github.com/Hazer-BJTU/pyattacker/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE)
+
+> Run tens of thousands of independent tasks to completion — resumably, observably, and without
+> reimplementing endpoint pools, retries and "which rows already ran" for the fifth time.
+
+## The situation this is for
+
+Picture a long workflow test, a model benchmark, or any experiment made of many independent items.
+Three hours in, one network request fails. The process dies — and you have no idea *which stage*
+each item actually reached. Rerunning from scratch means paying for every request that already
+succeeded, so you start writing a `results.jsonl` and a "skip what's already in there" check.
+
+Then the provider starts rate-limiting you. A single API key serialises your parallel requests into
+a queue, so you add a second key, a third, and now you need to decide which request goes where, what
+happens when one endpoint starts returning 429s, and whether a failure means *retry* or *give up*.
+Somewhere in there, `asyncio.Semaphore` stops being enough and you are writing a scheduler.
+
+pyattacker is that scheduler, extracted and made boring:
+
+* **a failure costs you one task, not the run** — every task's output is persisted the moment it is
+  produced, so `resume` restarts at the first task that produced nothing, and re-sends nothing that
+  already succeeded;
+* **endpoints are a pool, not a global variable** — capacity, health, and quota per endpoint, leased
+  through `async with`, with seven policies for choosing which one to use and how to wait;
+* **the record is queryable, not a log file** — every attempt, every retry decision (`{retry, reason,
+  delay_s, error_class}`), every intermediate artifact, in SQLite you can `SELECT` from while the run
+  is still going.
+
+It **does not touch the network**: you write the openai/anthropic calls, it handles everything around
+them. The core dependency list is the standard library plus PyYAML.
+
+**New here?** The [tutorial](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) goes from a five-line program to a sharded, resumable
+model evaluation. Every snippet in it is executed by the test suite.
+
+## Install
+
+```bash
+uv add pyattacker            # or: pip install pyattacker
+```
+
+From a clone:
+
+```bash
+git clone https://github.com/Hazer-BJTU/pyattacker && cd pyattacker
+uv sync
+uv run pyattacker demo       # zero-config smoke test: 50 simulated pipelines, retries, a report
+```
+
+Requires Python 3.11+.
+
+## Core Model
+
+Five concepts, and that is the whole vocabulary:
+
+| Concept | Meaning | In one line |
+|---|---|---|
+| **artifact** | the persisted state of a task | content-addressed, **persisted as soon as it is produced** → checkpoint granularity = task |
+| **task** | the smallest unit of scheduling | a unary `(artifact) -> artifact` function, sync or async |
+| **pipeline** | the unit of completion | `fetch \| ask \| judge \| metrics` chained linearly, semantically independent of each other |
+| **resource** | a leasable external capability | one endpoint / one key; once pooled, it can be published and subscribed to concurrency-safely |
+| **algorithm** | the policy for acquiring resources | `wait`, `backoff`, `least_busy`, `failover`, `sticky`, `quota_aware`, `immediate` — orthogonal to "retry on failure" |
+
+## 30-Second Quickstart (SDK)
+
+```python
+from pyattacker import Pool, Resource, Retrying, Runner, pipeline, task
+
+@task("ask", resource="apis", algorithm="backoff",
+      retry=Retrying(max_attempts=4, base=0.5, cap=30.0), timeout_s=60)
+async def ask(row: dict, ctx) -> dict:
+    async with ctx.acquire(model="gpt-4o") as lease:     # returned on exit; returned on exception too
+        text = await lease.client.chat(row["q"])         # lease.client is built by resource.factory
+        lease.report(ok=True, usage={"tokens": 128})     # report health/quota back to the pool
+        return {"q": row["q"], "a": text}
+
+pool = Pool("apis",
+            [Resource.create("llm", capacity=4, options={"model": "gpt-4o"},
+                             factory=lambda res: MyClient(res.options)) for _ in range(8)],
+            algorithm="backoff")
+
+template = pipeline("qa", ask)
+
+with Runner(store="runs/qa.db", pools=[pool], concurrency=64) as runner:
+    report = runner.run(template.map(dataset_rows))   # a generator, streaming, memory O(concurrency)
+    print(report.summary())
+    report.export_jsonl("runs/qa.jsonl")
+```
+
+Want pass@k? `template.map(rows, repeats=3)` — the same seed expands into three independent pipelines.
+
+## Lease Safety: The Framework's Hardest Guarantee
+
+Resource leasing is the most critical point of interaction between your code and the framework, so:
+
+```python
+async with ctx.acquire(resource) as lease:   # ← the only recommended form
+    for chunk in chunks:                      # repeatedly acquiring/releasing inside a loop is fine too
+        ...
+```
+
+* An exception, a cancellation, a `timeout_s` timeout — **always returned**;
+* Forgot to release through the escape hatch `await ctx.acquire_lease()`? It is **force-reclaimed** when the
+  task ends, and a `lease.leaked` event is recorded;
+* Reclaim is a **pure synchronous function**, and `CancelledError` cannot interrupt it — this is why "a task
+  never holds a resource after it ends" holds;
+* When you need something stricter, `strict_leases=True`: a leak immediately fails that task (`LeaseLeakError`).
+
+## Scheduling That Keeps Its Promises
+
+* **A retry backoff does not hold a worker.** When the policy wants another attempt, the pipeline is parked in
+  a delay queue and the worker immediately picks up other work. `concurrency` therefore means *attempts in
+  flight*, not *pipelines sitting out a 30-second backoff*.
+* **A parked pipeline is never mistaken for a dead one.** The end of a run waits for parked pipelines too; a
+  stop records them as `interrupted` with their checkpoints intact, so `resume` picks them up.
+* **Pool wakeups are targeted.** Releasing one resource wakes only the waiters whose selector can use it,
+  instead of every blocked pipeline.
+* **History is batched, checkpoints are not.** Attempts and events are written in batches (size, interval,
+  heartbeat, and end-of-run), while artifacts and checkpoints are always committed immediately. `SIGKILL` can
+  cost you the last batch of history, never a checkpoint. `--no-write-behind` opts out.
+* **Waiting is measured.** Pool stats report `waits_total`, `wait_ms_avg`, `p50`, `p95` and `max`, and a wait
+  beyond `slow_wait_ms` emits an `acquire.slow_wait` event you can alert on.
+
+## Semantic Recovery
+
+Every successful task persists its artifact and advances the checkpoint. On resume:
+
+```python
+runner.run(template.map(rows), resume=True)   # or pyattacker resume -c config.yaml
+```
+
+* Already successful pipelines → skipped outright;
+* Failed pipelines → continue from **the first task that produced no artifact**: **if task C died, only task C
+  reruns, and task B's request is not re-sent**;
+* The seed artifact is persisted too → recovery **does not depend on the original dataset file**;
+* Changed a task's source code (`spec_digest` includes source digests) → treated as a new pipeline, so old
+  results are not incorrectly reused.
+
+## Running It Across Processes (Sharding)
+
+SQLite takes one writer and the kernel is a single event loop, so scale means **processes with their own
+stores**, joined afterwards. A pipeline's shard comes from its content-addressed key, so the same dataset always
+splits the same way and `--resume` puts every pipeline back where it was:
+
+```bash
+# convenience: N children, then a merged report
+uv run pyattacker run -c examples/qa_eval.yaml --shards 4 --jobs 4 --store runs/qa.db
+# -> runs/qa.shard0of4.db … runs/qa.shard3of4.db
+
+# or drive each shard yourself (cluster, scheduler, four terminals)
+uv run pyattacker run -c examples/qa_eval.yaml --shard 0/4 --store runs/qa.shard0.db
+uv run pyattacker resume -c examples/qa_eval.yaml --shard 0/4 --store runs/qa.shard0.db
+
+# one coherent answer out of N files (de-duplicated, statistics recomputed)
+uv run pyattacker report runs/qa.shard*of4.db
+uv run pyattacker export runs/qa.shard*of4.db runs/all.jsonl
+uv run pyattacker export runs/qa.shard*of4.db runs/tasks.csv --rows tasks --format csv
+```
+
+`--rows` picks the shape: `pipelines` (nested, default), `tasks`, `attempts` (including each retry `decision`),
+`events`, `artifacts`. `--format` picks `jsonl`, `json` or `csv`.
+
+## Declarative (Simple Tasks)
+
+The YAML describes **composition and resources**; the logic stays in Python (`use: my_pkg.tasks:ask`).
+
+```yaml
+run:   { store: runs/demo.db, concurrency: 8, label: demo }
+pools:
+  apis:
+    kind: llm
+    algorithm: backoff
+    resources: [ { id: api-1, capacity: 4, options: { model: gpt-4o } } ]
+pipeline:
+  name: qa
+  tasks:
+    - { use: pyattacker.tasks:echo }
+    - { use: pyattacker.tasks:simulate_llm, resource: apis, algorithm: backoff,
+        retry: { max_attempts: 3, on: [RetryableError, TimeoutError] } }
+source: { kind: range, n: 100 }
+```
+
+```bash
+uv run pyattacker validate -c examples/qa_eval.yaml
+uv run pyattacker run      -c examples/qa_eval.yaml --progress
+uv run pyattacker watch    runs/demo.db          # open another process to monitor it live
+uv run pyattacker report   runs/demo.db --errors 20
+uv run pyattacker export   runs/demo.db out.jsonl
+uv run pyattacker serve    runs/demo.db          # HTTP dashboard + JSON endpoints
+uv run pyattacker plugins                        # installed plugins
+```
+
+Exit codes: `0` all succeeded / `1` some failed / `2` config error / `130` interrupted.
+Every flag of every subcommand: [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/cli.md).
+
+## Records and Monitoring
+
+The complete story of one pipeline = five tables queried by `pipeline_id`: state and checkpoint, the final
+state of each task, the full attempt history (including **every retry decision**
+`{retry, reason, delay_s, error_class}`), intermediate and final artifacts, and the structured event stream.
+`pyattacker report/watch` consumes these facts directly.
+
+## Extending It
+
+**Plugins** are ordinary `importlib.metadata` entry points — install a package and its names become
+usable from any config:
+
+```toml
+[project.entry-points."pyattacker.tasks"]
+my_judge = "my_pkg.tasks:my_judge"        # a TaskSpec, or a factory returning one
+[project.entry-points."pyattacker.algorithms"]
+my_algo  = "my_pkg.algo:MyAlgorithm"
+[project.entry-points."pyattacker.stores"]
+s3       = "my_pkg.s3:open_store"         # keyed by URI scheme: store = "s3://bucket/runs.db"
+```
+
+```bash
+uv run pyattacker plugins                 # what is installed, and what failed to load
+```
+
+Built-ins resolve first (a plugin cannot shadow `echo`), and a plugin that raises on import is
+recorded rather than fatal. A complete worked example: [`examples/plugin_package/`](https://github.com/Hazer-BJTU/pyattacker/blob/main/examples/plugin_package/README.md).
+
+**Large payloads** can live outside the database:
+
+```bash
+uv run pyattacker run -c examples/qa_eval.yaml --artifact-backend file:///data/blobs
+# or, in the config:  artifact_backend = { kind = "file", root = "/data/blobs", min_bytes = 262144 }
+```
+
+Files are content-addressed, written atomically, and hydrated back on read — so a resumed run
+reuses spilled checkpoints transparently. `null` keeps digests and drops bytes; `inline` (default)
+keeps everything in the store.
+
+**A zero-dependency monitoring endpoint**:
+
+```bash
+uv run pyattacker serve runs/qa.db        # http://127.0.0.1:8787
+# /  dashboard   /stats  /events  /pipelines  /resources  /errors   (JSON)
+```
+
+It opens a fresh read-only connection per request, so it runs happily beside a live run. It has **no
+authentication** and binds to loopback: it exposes your payloads, so treat it as a debug view and do not
+put it on a public interface without your own proxy in front.
+
+**Branching inside a step** — `fanout(a, b)` runs several tasks on the same input concurrently and
+returns `{task_name: value}`. Retry granularity becomes the group, which is the honest price of not
+turning pipelines into a DAG. The group is the only spec the Runner sees, so `resource`, `algorithm` and
+`timeout_s` are inherited from the children when all of them agree (a `timeout_s` then bounds the whole
+group).
+
+## Documentation
+
+| Document | What is in it |
+|---|---|
+| [`docs/tutorial.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/tutorial.md) | fourteen runnable steps, from "one task" to a sharded evaluation; each one executed by the test suite |
+| [`docs/reference.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/reference.md) | every public class and function: signatures, parameters, examples |
+| [`docs/cli.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/cli.md) | every subcommand, every flag, exit codes, config reference |
+| [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md) | conceptual model, the six invariants, the lease contract, data model, tradeoffs |
+| [`CHANGELOG.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/CHANGELOG.md) | what changed, release by release |
+
+## Examples
+
+| Example | What it shows |
+|---|---|
+| [`examples/quickstart.py`](https://github.com/Hazer-BJTU/pyattacker/blob/main/examples/quickstart.py) | the SDK in 60 lines: a custom client factory, retries, resume |
+| [`examples/llm_eval/`](https://github.com/Hazer-BJTU/pyattacker/blob/main/examples/llm_eval/README.md) | a complete evaluation — prepare → 2-turn model call → 3 judges → reduce, in **two pipeline shapes**, with the checkpoint-granularity tradeoff *measured* (grouped re-sent 2 judge requests that had already succeeded; split re-sent 0) |
+| [`examples/sharded.py`](https://github.com/Hazer-BJTU/pyattacker/blob/main/examples/sharded.py) | one dataset across N stores, then a merged report |
+| [`examples/plugin_package/`](https://github.com/Hazer-BJTU/pyattacker/blob/main/examples/plugin_package/README.md) | a real installable plugin: tasks, an algorithm, a codec |
+| [`examples/qa_eval.yaml`](https://github.com/Hazer-BJTU/pyattacker/blob/main/examples/qa_eval.yaml) | the declarative path, end to end |
+
+```bash
+uv run python examples/quickstart.py
+uv run python -m examples.llm_eval.demo
+uv run python examples/sharded.py
+uv run pyattacker run -c examples/qa_eval.yaml --limit 40
+```
+
+## Out of Scope
+
+These are design decisions, not missing features:
+
+* **Network requests** — you write the openai/anthropic protocols yourself. The kernel never opens a socket.
+* **Semantic reduction** — accuracy, pass@k, F1 and any cross-pipeline aggregation. Export the artifacts and
+  compute it outside, or write a sink pipeline out of the primitives.
+* **DAG orchestration** — a pipeline is a linear chain; branch inside a task with `fanout`.
+* **A serving gateway** — the only HTTP surface is the read-only debug endpoint above.
+* **Distributed scheduling** — scale out with `--shard`; multi-process is the ceiling.
+
+Sections 1 and 11 of [`docs/design.md`](https://github.com/Hazer-BJTU/pyattacker/blob/main/docs/design.md) state the boundary precisely, and section 8 lists
+every known tradeoff with its reason.
+
+## Status
+
+**0.1.0 — the first release.** Everything planned for it is implemented (M0–M4: the kernel, persistence and
+task-level recovery, retries and error classification, the resource pool with 7 acquisition algorithms,
+delayed continuations and write-behind batching, sharding and merged reports, five export shapes in three
+formats, entry-point plugins, external artifact backends, the fan-out helper, and the HTTP monitoring
+endpoint). The API is young: it follows semantic versioning from here, but expect refinement before 1.0.
+
+Left for later: a distributed scheduler, Parquet export, blob garbage collection, and first-class
+`Parallel`/`Gather` nodes.
+
+## Development
+
+```bash
+uv sync                      # create the venv + install dependencies (the only core dependency is pyyaml)
+uv run pytest                # the whole suite: zero network, a few seconds
+uv run ruff check            # lint (configuration lives in pyproject.toml, with reasons for each exception)
+uv run pyattacker demo       # end-to-end smoke test
+uv build                     # sdist + wheel
+```
+
+Tests are offline and deterministic (time goes through an injectable `Clock`). The tutorial's code blocks are
+extracted and executed by `tests/test_tutorial.py`, so documentation that rots fails CI.
+
+## License
+
+MIT — see [LICENSE](https://github.com/Hazer-BJTU/pyattacker/blob/main/LICENSE).
+