evalshift-sdk 0.2.0__tar.gz

evalshift_sdk-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Sync (dev group)
+        run: uv sync --locked
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+      - name: Mypy (strict)
+        run: uv run mypy
+
+      - name: Pytest
+        run: uv run pytest

evalshift_sdk-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,103 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  # Manual re-run for a tag whose release run failed or never fired. The version
+  # check still gates the publish, so this cannot ship a mismatched artifact.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to release (e.g. v0.2.0)"
+        required: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # On a tag push this is the tag; on a manual dispatch it is the tag
+          # the operator named, so both paths build the same commit.
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Sync (dev group)
+        run: uv sync --locked
+
+      - name: Ruff lint
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
+      - name: Mypy (strict)
+        run: uv run mypy
+
+      - name: Pytest
+        run: uv run pytest
+
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # On a tag push this is the tag; on a manual dispatch it is the tag
+          # the operator named, so both paths build the same commit.
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      # The tag is the release's source of truth; refuse to publish a wheel whose
+      # version disagrees with it, which is how a v0.2.0 tag ships 0.1.0 artifacts.
+      - name: Verify tag matches package version
+        env:
+          RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
+        run: |
+          tag="${RELEASE_TAG#v}"
+          pkg="$(uv version --short)"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::tag v$tag does not match package version $pkg"
+            exit 1
+          fi
+          echo "tag and package version agree: $pkg"
+
+      - name: Build
+        run: uv build
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Required for PyPI trusted publishing (OIDC). No API token is used.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

evalshift_sdk-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments / tooling caches
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Capture output (the SDK writes here at runtime)
+.evalshift/
+
+# OS / editor
+.DS_Store
+
+# Local agent tooling and internal design notes (not part of the published SDK)
+.claude/
+.superpowers/
+docs/superpowers/

evalshift_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [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).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-06
+
+First release published to PyPI. Everything below describes the behavior of that
+initial release rather than a delta from a previous one.
+
+### Behavior
+
+- **Capture is OFF by default.** Nothing is recorded or written unless `EVALSHIFT_CAPTURE`
+  is set to a truthy value, so instrumentation is safe to leave in production code paths.
+
+- **Hygiene is ON by default (bounded but generous).** `dedup` defaults to `True` and
+  `max_captures` to `200` per suite directory, so a host that enables capture but never calls
+  `configure(...)` does not grow `.evalshift/captures/` without limit. `capture_ttl` and
+  `sample_rate` are off by default (`active_sink()` wraps in a `HygieneSink` unless every
+  hygiene knob is disabled). For fully unbounded capture, set
+  `EVALSHIFT_MAX_CAPTURES=0 EVALSHIFT_DEDUP=off` (or `configure(dedup=False, max_captures=None)`).
+
+### Added
+
+- Env vars now set the hygiene defaults, so no code change is needed to tune capture volume:
+  `EVALSHIFT_MAX_CAPTURES` (`0`/`none`/`unlimited` = uncapped), `EVALSHIFT_DEDUP`,
+  `EVALSHIFT_CAPTURE_TTL` (seconds), `EVALSHIFT_SAMPLE_RATE`. Precedence is
+  `configure(...)` > env var > built-in default; a malformed value fails open to the default.
+
+- `configure(require_model_call=True)` opt-in persistence gate: when set, an agent
+  invocation that records no `model_call` span (a run that short-circuits before its
+  model call, or is cancelled beforehand) is dropped at `_finalize` instead of writing
+  a content-free capture. Off by default, so the write-per-sampled-invocation contract
+  and error-only telemetry are unchanged. Read via `config.require_model_call()`; the
+  predicate is `evalshift.capture.span.is_persistable(tree)`.
+
+- `build_capture` gained optional `conversation_id` / `turn_index` /
+  `parent_capture_id` keyword parameters (schema 1.1.0), threaded through to
+  the emitted `CaptureEnvelope`. The public capture API — `_finalize`,
+  `@capture.agent(...)`, `capture.agent_session(...)`, and
+  `capture.agent_session_async(...)` — gained the same three keyword-only
+  parameters, all defaulting to `None` so existing callers are unaffected.
+  `agent_session` / `agent_session_async` are the recommended way to stamp
+  per-turn identity on a dynamic multi-turn conversation (fresh values per
+  `with` / `async with`); the `@capture.agent` decorator's values are static
+  per decoration.
+- `input_hash` now folds `conversation_id` and `turn_index` into the hash
+  whenever `conversation_id` is set, so distinct turns of one conversation
+  that share identical `agent_input` text (e.g. "yes", "1pm") no longer
+  collapse under the `(suite, input_hash)` dedup key. When `conversation_id`
+  is unset, `input_hash` stays byte-identical to prior releases.
+- `docs/SCHEMA.md` documents the 1.1.0 envelope fields, the messages-list
+  convention for `capture.model_call(input=...)` on multi-turn agents, and
+  why `input_hash` changes shape for conversation turns.
+- `tests/conformance/cli_models_vendored.py` gained a vendored
+  `CaptureEnvelope` model (mirroring `evalshift-cli`'s
+  `evalshift.captures.models.CaptureEnvelope`, `extra="ignore"`) so the whole
+  envelope — not just the inner trace — validates against the CLI contract in
+  conformance tests.
+- MIT `LICENSE` file. The SDK is imported into user applications, so it ships under
+  MIT rather than the AGPL-3.0-or-later used by the EvalShift server and CLI.
+
+[Unreleased]: https://github.com/babaliauskas/evalshift-sdk/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/babaliauskas/evalshift-sdk/releases/tag/v0.2.0