ai-agent-ledger-py 0.2.1__tar.gz

ai_agent_ledger_py-0.2.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,69 @@
+name: Bug report
+description: Something behaved differently from what the documentation says.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time. Two things make a bug report far easier to act on:
+
+        1. The output of `al demo` — it exercises the real code paths end to end.
+        2. If the problem is about *routing* (the wrong agent chosen, or none chosen),
+           the candidate list from `grid.candidates(task)`. Every signal is kept
+           visible precisely so routing can be diagnosed without guesswork.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you observed, and what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: A minimal script or command sequence. If it needs a registry, describe the response shape rather than a private URL.
+      placeholder: |
+        1. `al demo`
+        2. ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Full traceback or output
+      description: Paste it verbatim. Do not trim the middle — the frame that matters is often the one that looks irrelevant.
+      render: shell
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `al --version`.
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python and OS
+      placeholder: "3.12.1 on Windows 11 / 3.11.7 on Ubuntu 24.04"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: integrity
+    attributes:
+      label: If this is about receipts, verification or the ledger
+      description: |
+        Known and already documented — please check these before filing, so the
+        issue tracker stays useful. `docs/DESIGN.md` has the honest limitations
+        list, and `SECURITY.md` repeats it as a table of what is already known.
+      options:
+        - label: I read the Limitations section of docs/DESIGN.md and this is not one of them.
+          required: false

ai_agent_ledger_py-0.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/yaoyuxiang-gnn/agent-ledger/security/advisories/new
+    about: Report privately. Do not open a public issue for anything exploitable.
+  - name: Question or idea
+    url: https://github.com/yaoyuxiang-gnn/agent-ledger/discussions
+    about: For "how do I…" and design discussion, which is not an issue.
+  - name: Known limitations
+    url: https://github.com/yaoyuxiang-gnn/agent-ledger/blob/main/docs/DESIGN.md
+    about: What each layer does and does not prove, and what is deliberately not built yet. Check here first.

ai_agent_ledger_py-0.2.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,61 @@
+name: Feature request
+description: Propose a change in behaviour, an adapter, or an integration.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, `CONTRIBUTING.md` has a "What would help most" list, and
+        `docs/DESIGN.md` has the honest limitations. If your idea is already on
+        either, a comment there is more useful than a new issue.
+
+        Two constraints shape what can be merged, and proposals that respect them
+        move much faster:
+
+        - **Zero runtime dependencies.** The `dependencies` list must stay empty;
+          a CI job fails the build if it does not. Optional extras are fine —
+          `[sign]` is the expected shape for anything that needs a library.
+        - **Denials stay data.** A refusal is a `PolicyDecision`, not an exception.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve
+      description: Describe the situation you are in, not the API you want. The API is usually easier to get right once the problem is clear.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you propose
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      multiple: true
+      options:
+        - Discovery (ARD)
+        - Matching and reputation
+        - Policy
+        - Delegation and receipts
+        - Ledger and storage
+        - Execution / A2A executor
+        - CLI
+        - Docs
+        - Other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: constraints
+    attributes:
+      label: Constraints
+      options:
+        - label: This can be done without adding a runtime dependency (or as an opt-in extra).
+          required: false
+        - label: I am willing to open a pull request for this.
+          required: false

ai_agent_ledger_py-0.2.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,42 @@
+## What this changes
+
+<!-- One or two sentences. If it fixes an issue, link it. -->
+
+## Why
+
+<!-- The problem, not the patch. What goes wrong today? -->
+
+## Breaking changes
+
+<!--
+Receipt digests are deterministic on purpose. If you changed `Receipt.body()` or
+the canonicalisation, existing ledgers will report as tampered. Say so here, and
+add it to CHANGELOG.md under Unreleased.
+-->
+
+- [ ] No breaking change
+- [ ] Breaking change, described above and in `CHANGELOG.md`
+
+## Checklist
+
+- [ ] `python -m pytest` passes (no install needed — `tests/conftest.py` shims `src` onto `sys.path`)
+- [ ] `python -m agent_ledger.cli demo --no-color` still runs — the demo is the README's front door
+- [ ] `ruff check src tests` and `ruff format --check src tests` pass
+- [ ] A test fails without this change
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`
+
+## Constraints this project keeps
+
+- [ ] **No runtime dependency added.** `dependencies` stays empty; a CI job fails the build if it does not. Anything needing a library ships as an opt-in extra (`[sign]` is the expected shape).
+- [ ] **No network in tests.** Everything goes through the `Transport` protocol; use `StaticTransport`.
+- [ ] **The demo stays offline and key-free.**
+- [ ] **Denials stay data.** A refusal is a `PolicyDecision`, not an exception.
+- [ ] If this touches `verify()`, `content_digest()` or `Receipt`, I added a **negative** test — tampered digest, wrong key, missing field, hostile line — not only the happy path.
+
+## How it was verified
+
+<!--
+Commands you ran and what they printed. If you changed the CLI, the demo
+transcript, or anything the README quotes, say whether the README needed
+updating — a README that describes the old behaviour is a bug.
+-->

ai_agent_ledger_py-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,128 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        exclude:
+          # Keep the matrix honest without spending minutes on redundant runs.
+          - os: windows-latest
+            python: "3.11"
+          - os: macos-latest
+            python: "3.11"
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest -q
+
+      - name: Demo must run on a clean checkout
+        # The offline demo is the project's front door. If it breaks, the
+        # README breaks, so it is a CI gate rather than a smoke test.
+        run: python -m agent_ledger.cli demo --no-color
+        env:
+          NO_COLOR: "1"
+
+      - name: READMEs must still describe this software
+        # Documentation drifts in one direction: it describes the version someone
+        # was proud of. This checks the claims that can be checked — every
+        # documented command and flag exists, the quoted test count is real, the
+        # demo transcript still matches, and the Chinese README has not fallen
+        # behind the English one.
+        run: python tools/check_readme.py
+        env:
+          NO_COLOR: "1"
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip ruff
+      - run: ruff check src tests
+      - run: ruff format --check src tests
+
+  zero-dependency:
+    name: no runtime dependencies
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Assert the package declares no runtime dependencies
+        # Zero dependencies is a headline promise in the README. This job is
+        # what keeps it true.
+        run: |
+          python - <<'PY'
+          import pathlib, re, sys
+
+          text = pathlib.Path("pyproject.toml").read_text(encoding="utf-8")
+          match = re.search(r"^dependencies\s*=\s*\[(.*?)\]", text, re.S | re.M)
+          if match is None:
+              sys.exit("could not find a dependencies key in pyproject.toml")
+          body = match.group(1).strip()
+          if body:
+              sys.exit(f"runtime dependencies must stay empty, found: {body!r}")
+          print("ok: no runtime dependencies declared")
+          PY
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - name: Assert the artefacts contain only what they should
+        # The checks live in tools/audit_dist.py rather than inline so that this
+        # job and the release workflow run the *same* ones — a release that is
+        # stricter or laxer than CI is a release nobody checked. The audit also
+        # asserts what an inline snippet cannot: that the version in the wheel
+        # matches pyproject.toml and _identity.py, and that the console scripts
+        # survived whatever the distribution name is this month.
+        run: python tools/audit_dist.py
+      - name: The metadata must render on PyPI
+        # README.md is the PyPI long description; a malformed one is rejected at
+        # upload time, long after the build that could have caught it.
+        run: python -m twine check --strict dist/*
+      - name: Install the built wheel in isolation
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/python -m pip install dist/*.whl
+          /tmp/clean/bin/al demo --no-color > /dev/null
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

ai_agent_ledger_py-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+# Publishing is triggered by a *published GitHub release*, not by a tag push.
+#
+# A tag is a ref, and a ref can be moved; a release is a deliberate act with a
+# human on the other end of it. The distinction matters here because a version
+# number on PyPI can be yanked but never reused — the one mistake in this
+# workflow that cannot be repaired — so the trigger is the event with the most
+# intent behind it.
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to upload. Use testpypi to rehearse the whole path."
+        type: choice
+        options: [pypi, testpypi]
+        default: testpypi
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build and check the artefacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: The tag must name the version being published
+        # PyPI will reject a second upload of an existing version, and the version
+        # number is burned either way. Catching the mismatch here — before the
+        # build — is the difference between a red X and a release nobody can redo.
+        if: github.event_name == 'release'
+        run: |
+          python - <<'PY'
+          import os, pathlib, re, sys
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          text = pathlib.Path("pyproject.toml").read_text(encoding="utf-8")
+          version = re.search(r'^version\s*=\s*"([^"]+)"', text, re.M).group(1)
+          if tag.lstrip("v") != version:
+              sys.exit(f"tag {tag!r} does not match pyproject version {version!r}")
+          print(f"ok: tag {tag} == version {version}")
+          PY
+
+      - name: Build
+        run: python -m build
+
+      - name: Check the artefacts, and that the metadata renders
+        # The same audit CI runs, plus the twine check that only matters at
+        # upload time — README.md is the PyPI long description, and a malformed
+        # one is rejected after the build rather than during it.
+        run: |
+          python tools/audit_dist.py
+          python -m twine check --strict dist/*
+
+      - name: The wheel must run on its own
+        # Everything above inspects the artefact. This runs it — installed into a
+        # clean interpreter, with no `src` on the path and no source tree in
+        # sight, which is the only configuration a PyPI user will ever have.
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/python -m pip install dist/*.whl
+          /tmp/clean/bin/al demo --no-color > /dev/null
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to ${{ github.event_name == 'release' && 'PyPI' || inputs.target }}
+    needs: build
+    runs-on: ubuntu-latest
+
+    # Must match the environment named in the PyPI Trusted Publisher. It is also
+    # what lets you require a reviewer before a release reaches the world, which
+    # is the only remaining human gate in this path.
+    environment:
+      name: ${{ github.event_name == 'release' && 'pypi' || 'testpypi' }}
+      url: ${{ github.event_name == 'release' && 'https://pypi.org/p/ai-agent-ledger-py' || 'https://test.pypi.org/p/ai-agent-ledger-py' }}
+
+    permissions:
+      # The OIDC token that replaces an API token. Without this the upload cannot
+      # authenticate, and there is deliberately no secret to fall back on.
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ github.event_name == 'release' && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}

ai_agent_ledger_py-0.2.1/.gitignore

@@ -0,0 +1,147 @@
+# What may be published
+#
+# This file is deliberately explicit rather than exhaustive. A deny-list only
+# stops the leaks somebody already thought of; the next stray file — a release
+# plan, a strategy note, a scratch analysis — walks straight past it. So the
+# rules below name the *few* local-only directories instead, and everything else
+# here is the ordinary build and editor cruft.
+#
+# The rule this encodes: **anything that is not the product or its public
+# documentation does not get committed.** If you are unsure whether a file is
+# product, it is not.
+
+
+# --------------------------------------------------------------------------- #
+# Local-only working material. NEVER published.
+# --------------------------------------------------------------------------- #
+
+# Strategy, planning, launch notes, competitive analysis, anything written for
+# us rather than for a reader. Kept on disk because it is useful; kept out of
+# git because a repository is a publication, not a folder.
+.internal/
+.notes/
+.planning/
+private/
+
+# Security audits and threat models. These are the one category where publishing
+# is actively harmful: a document that lists weaknesses by file and line is a
+# map for anyone who wants to use them, and "the issues are fixed" is not a
+# reason to hand over the map.
+AUDIT-*.md
+THREAT-MODEL*.md
+SECURITY-AUDIT*.md
+
+# Release and launch plans. How a project intends to earn attention is not part
+# of what it does, and it reads badly to the people whose attention is wanted.
+RELEASE*.md
+LAUNCH*.md
+STRATEGY*.md
+ROADMAP-INTERNAL*.md
+
+# Scratch, drafts, and one-off analysis scripts
+_scratch*.*
+_dbg*.*
+_tmp*.*
+*.draft.md
+TODO.local.md
+
+
+# --------------------------------------------------------------------------- #
+# Python build and cache artefacts
+# --------------------------------------------------------------------------- #
+
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+sdist/
+
+
+# --------------------------------------------------------------------------- #
+# Virtual environments
+#
+# `.venv-*/` is listed as well as `.venv/` because `.venv/` does NOT match
+# `.venv-test/`. That distinction is not cosmetic: hatchling honours .gitignore
+# when assembling an sdist, so one missing pattern once produced a 16 MB sdist
+# containing an entire virtualenv, `python.exe` included. Every environment
+# directory name in use must be covered here.
+# --------------------------------------------------------------------------- #
+
+.venv/
+.venv-*/
+venv/
+venv-*/
+env/
+ENV/
+
+
+# --------------------------------------------------------------------------- #
+# Test, coverage and lint caches
+# --------------------------------------------------------------------------- #
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+
+# --------------------------------------------------------------------------- #
+# Ledgers and key material produced by running the thing
+#
+# Receipts are evidence and keys are keys; neither belongs in a source
+# repository. Fixtures are the exception, and are re-included explicitly.
+# --------------------------------------------------------------------------- #
+
+*.jsonl
+!tests/fixtures/*.jsonl
+
+# Trust stores and signed bundles. A keyring holds public keys, but publishing
+# one is an operational decision, not a side effect of running a command.
+keyring.json
+*keyring*.json
+*.bundle.json
+secrets.json
+
+# Never, under any circumstance
+.env
+.env.*
+*.pem
+*.key
+id_rsa*
+id_ed25519*
+*.p12
+*.pfx
+
+
+# --------------------------------------------------------------------------- #
+# Documentation build output
+# --------------------------------------------------------------------------- #
+
+docs/_build/
+site/
+
+
+# --------------------------------------------------------------------------- #
+# Editors and operating systems
+# --------------------------------------------------------------------------- #
+
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+desktop.ini