agent-handshake 0.7.0__tar.gz

agent_handshake-0.7.0/.coderabbit.yaml

@@ -0,0 +1,23 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: en-US
+
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  review_status: true
+  collapse_walkthrough: true
+  poem: false
+  sequence_diagrams: false
+  # Review the shipped code and its tests; docs, examples and assets are skipped.
+  path_filters:
+    - "src/**"
+    - "tests/**"
+    - "action.yml"
+    - ".github/workflows/**"
+  auto_review:
+    enabled: true
+    drafts: false
+
+chat:
+  auto_reply: true

agent_handshake-0.7.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,48 @@
+name: Bug report
+description: Something is broken or behaving unexpectedly.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in as much as you can.
+
+  - type: input
+    id: version
+    attributes:
+      label: agent-handshake version
+      placeholder: "0.7.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: The smallest code / config that triggers the issue.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback
+      description: Paste the full error output here (if any).
+      render: text

agent_handshake-0.7.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,30 @@
+name: Feature request
+description: Propose a new feature or improvement.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before submitting, search open issues to avoid duplicates.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve? What use case is blocked without it?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should the feature look like? API sketches, CLI flags, config keys — whatever helps.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds exist today? Why are they insufficient?

agent_handshake-0.7.0/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    groups:
+      dev-deps:
+        patterns:
+          - "ruff"
+          - "mypy"
+          - "pytest*"
+          - "pre-commit"
+      core-deps:
+        patterns:
+          - "typer"
+          - "rich"
+          - "pyyaml"
+          - "pydantic"
+          - "jsonschema"
+          - "httpx"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday

agent_handshake-0.7.0/.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- What does this PR do? One paragraph is enough. -->
+
+## Changes
+
+<!-- Bullet list of the concrete changes made. -->
+
+-
+
+## Test plan
+
+<!-- How was this tested? Check all that apply. -->
+
+- [ ] Added / updated unit tests
+- [ ] All existing tests pass (`pytest tests/`)
+- [ ] Lint and format clean (`ruff check src/ tests/ && ruff format --check src/ tests/`)
+- [ ] Type check passes (`mypy src/`)
+
+## Related issues
+
+<!-- Fixes #N  /  Related to #N  /  N/A -->

agent_handshake-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,langchain]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Format check
+        run: ruff format --check src/ tests/
+
+      - name: Type check
+        run: mypy src/
+
+      - name: Test with coverage
+        run: pytest tests/ -v --tb=short --cov=agent_handshake --cov-report=term-missing
+
+      - name: Verify clean import (no optional deps)
+        run: |
+          pip install -e "."
+          python -c "import agent_handshake; print(agent_handshake.__version__)"
+          python -c "from agent_handshake import load_spec, validate_output, FunctionAdapter, SnapshotStore"
+
+      - name: Verify no unsafe yaml.load
+        run: |
+          if grep -rn "yaml\.load\b" src/; then
+            echo "FAIL: unsafe yaml.load found"
+            exit 1
+          else
+            echo "PASS: only yaml.safe_load used"
+          fi
+
+  action:
+    name: GitHub Action on the example
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Run the repository action with this commit
+        uses: ./
+        with:
+          package: ${{ github.workspace }}
+          working-directory: examples/customer_support
+          config: handshake/handshake.yaml
+          args: --no-semantic

agent_handshake-0.7.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: pip install -e "."
+
+      - name: Verify tag matches __version__
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER=$(python -c "import agent_handshake; print(agent_handshake.__version__)")
+          if [ "$TAG" != "$VER" ]; then
+            echo "Tag $TAG != __version__ $VER" && exit 1
+          fi
+
+      - name: Build
+        run: pip install build && python -m build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_handshake-0.7.0/.gitignore

@@ -0,0 +1,151 @@
+# ========================
+# Python
+# ========================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyo
+
+# Distribution / packaging
+dist/
+build/
+eggs/
+*.egg
+*.egg-info/
+src/*.egg-info/
+*.whl
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+parts/
+var/
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# ========================
+# Virtual environments
+# ========================
+.venv/
+venv/
+ENV/
+env/
+.python-version
+
+# ========================
+# Testing
+# ========================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# ========================
+# Type checking & Linting
+# ========================
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.ruff_cache/
+.pyre/
+
+# ========================
+# IDE / Editors
+# ========================
+.vscode/
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.idea/
+*.swp
+*.swo
+*~
+.project
+.settings/
+.history/
+*.code-workspace
+*.sublime-project
+*.sublime-workspace
+.spyderproject
+.spyproject
+.ropeproject
+
+# ========================
+# OS files
+# ========================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+*.bak
+*.tmp
+*.log
+
+# ========================
+# Environment / Secrets
+# ========================
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+
+# ========================
+# Jupyter Notebooks
+# ========================
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# ========================
+# Documentation builds
+# ========================
+site/
+_build/
+docs/_build/
+
+# ========================
+# Profiling
+# ========================
+*.prof
+*.lprof
+
+# ========================
+# Celery
+# ========================
+celerybeat-schedule
+celerybeat.pid
+
+# ========================
+# agent-handshake specific
+# ========================
+
+# Generated reports (not committed)
+handshake/reports/
+*.junit.xml
+report.md
+
+# NOTE: Snapshots ARE committed to git!
+# They are your test baselines for deterministic replay.
+# Do NOT add handshake/snapshots/ to .gitignore.

agent_handshake-0.7.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

agent_handshake-0.7.0/CHANGELOG.md

@@ -0,0 +1,175 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.0] - 2026-10-16
+
+### Changed
+- The project is renamed from a2a-spec to agent-handshake. The A2A protocol is
+  only one of the agent types it tests, and the old name read as an A2A-only
+  tool. New names: package `agent-handshake`, module `agent_handshake`,
+  command `handshake`, config file `handshake.yaml`, project folder
+  `handshake/`, pytest options `--handshake`, `--handshake-config`,
+  `--handshake-no-semantic`, ini option `handshake_config`, fixture
+  `handshake_check`, and the GitHub Action `padobrik/agent-handshake`.
+  `HandshakeError` and `HandshakeConfig` replace `A2ASpecError` and
+  `A2ASpecConfig`. The old names are not kept: the project had no users yet.
+
+### Added
+- `A2AAdapter` reads file parts. They go under `"files"` in the output: a URL
+  file keeps its `url`, a raw file is stored as `size` and `sha256`, and
+  `filename` and `mediaType` are kept. Before, a reply with a file part
+  raised `AdapterError`.
+
+## [0.6.0] - 2026-10-16
+
+### Added
+- `a2aspec infer` follows nested reads: `data["customer"]["tier"]`,
+  `data.get("customer", {}).get("tier")`, `"tier" in data["customer"]` and
+  reads through a local name such as `customer = data["customer"]`. The
+  generated spec has nested object schemas with their own `required` lists.
+- `a2aspec infer --check` compares nested reads with the nested schema. A spec
+  generated by an earlier version covers only the top-level object, so
+  `--check` now reports the nested fields; run `a2aspec infer --force` again.
+- `a2aspec record --agent ID` records only the given agents (repeatable).
+- A scenario can have an `agents` list. `a2aspec record` and
+  `a2aspec test --live` then call only those agents with its input. Before,
+  every agent in `ADAPTERS` got every scenario.
+
+### Changed
+- `a2aspec pipeline test` checks policy and semantic rules at each step, not
+  only structural rules. It has `--semantic/--no-semantic` like `a2aspec test`.
+  Without the `semantic` extra, a pipeline whose specs have semantic rules now
+  exits 1 with an install hint; pass `--no-semantic` to skip them.
+
+## [0.5.0] - 2026-10-16
+
+### Added
+- A GitHub Action (`uses: padobrik/a2a-spec@v0.5.0`) that installs a2a-spec,
+  runs `a2aspec infer --check` and `a2aspec test --format github`. CI runs it
+  on the example project.
+- Scenario `expectations` are checked: `a2aspec test` (replay and live) and the
+  pytest plugin fail when an agent's output does not have the expected value.
+  Before, the field in scenario files was ignored.
+
+### Fixed
+- `--format github` annotations use paths relative to the repository root, so
+  they attach to the spec file when the project is in a subdirectory.
+- `a2aspec pipeline test --mode live` never loaded `ADAPTERS` and failed on
+  the first agent. A failed agent call now fails only its test case, steps
+  without a spec show `NO SPEC` instead of `FAIL`, and unknown modes are
+  rejected.
+
+## [0.4.0] - 2026-10-16
+
+### Added
+- `a2aspec infer --check` compares every inferred spec with its consumer's
+  current code and fails when the code reads a field the spec does not cover.
+  Inferred specs record their consumer in the new `inferred_from` field, and
+  the pytest plugin runs the same check as a `consumer_code` test.
+- `a2aspec test --live` calls each spec's producer through `ADAPTERS` with
+  every scenario and checks the live output without saving it. Before, the
+  flag only changed the header and still replayed snapshots.
+
+### Changed
+- `a2aspec diff` rates a new field as LOW instead of HIGH, so adding a field
+  no longer fails CI; a removed field stays HIGH.
+
+### Fixed
+- `a2aspec record --suite` was ignored; it now records one scenario file.
+- `a2aspec test --format` was ignored. `junit` and `markdown` now print only
+  the report on stdout, and the new `github` format adds a GitHub Actions
+  annotation for each failure. Unknown formats are rejected.
+
+## [0.3.2] - 2026-10-16
+
+### Changed
+- README rewritten in Simplified Technical English with a verified Get started
+  guide and diagrams; it no longer documents `--format` and `--live`.
+
+### Fixed
+- The `a2aspec init` example spec: its PII regexes were double-escaped and
+  matched nothing, and its semantic rule lacked `source_field`/`target_field`
+  and always failed.
+- `a2aspec init` writes an `ADAPTERS` template and next steps that match the
+  current workflow.
+
+## [0.3.1] - 2026-10-15
+
+### Fixed
+- `a2aspec record` never found project adapters: `a2a_spec/adapters` was
+  shadowed by the library's own subpackage. Adapters now load from
+  `adapters_dir` (default `./a2a_spec/adapters`) and import errors are reported.
+- The customer support example records and imports correctly from its own
+  directory.
+- The `[record]`, `[done]` and `[diff]` labels were swallowed by rich markup.
+
+## [0.3.0] - 2026-10-15
+
+### Added
+- `A2AAdapter` calls agents that implement the A2A protocol 1.0 through
+  their Agent Card and the JSON-RPC binding; the card's version is recorded
+  in snapshots.
+
+### Changed
+- `Recorder` reads adapter metadata after the call instead of before.
+
+## [0.2.0] - 2026-10-15
+
+### Added
+- `a2aspec infer` generates a consumer-driven spec from the fields a consumer
+  function reads and the producer's recorded snapshots.
+- pytest plugin: with `--a2a` or the `a2a_config` ini option, spec files are
+  collected as tests (one per snapshot); the `a2a_check` fixture validates
+  live outputs.
+- `a2aspec skill` exports a bundled agent skill for coding agents.
+- `a2aspec diff --base REF` selects the git revision used as baseline.
+- `a2aspec test` evaluates `embedding_similarity` semantic rules against the
+  recorded input and output of each snapshot; `--no-semantic` skips them.
+- `LangChainAdapter` is exported from the package root.
+
+### Changed
+- **Breaking:** `a2aspec diff` requires snapshots tracked in git; it compares
+  against the version at `--base` (default `HEAD`).
+- Semantic rules using `entailment` or `language_detection` now fail with
+  "not implemented" instead of being silently ignored.
+- Custom policy validators receive the snapshot input instead of an empty dict.
+- The result header reports FAIL when any layer fails, not only structural.
+- Widened upper bounds for rich, langchain-core, sentence-transformers and dev tools.
+
+### Fixed
+- `a2aspec diff` reported no differences after re-recording, because
+  recording overwrites the snapshot file; it now compares against the
+  committed version and reports new and deleted scenarios.
+- `a2aspec diff` crashed without the `semantic` extra instead of falling back
+  to token overlap.
+- `LangChainAdapter` returns `{"content": ...}` for chat messages and uses
+  `model_dump()` for pydantic models instead of the deprecated `.dict()`.
+
+## [0.1.0] - 2026-02-19
+
+### Added
+- Initial public release of a2a-spec.
+- `SnapshotStore` with path-traversal protection.
+- `DiffEngine` for structural and semantic diff of agent outputs.
+- `PipelineExecutor` for DAG-based multi-agent pipeline testing.
+- CLI commands: `record`, `test`, `diff`, `pipeline`, `init`.
+- Frozen dataclasses for `FieldDiff`, `SemanticComparison`, `PolicyResult`.
+- Structured logging via `logging.getLogger(__name__)` in all modules.
+- CI matrix across Python 3.11, 3.12, 3.13.
+- Trusted Publishing workflow for PyPI releases.
+
+[0.7.0]: https://github.com/padobrik/agent-handshake/releases/tag/v0.7.0
+[0.6.0]: https://github.com/padobrik/a2a-spec/releases/tag/v0.6.0
+[0.5.0]: https://github.com/padobrik/a2a-spec/releases/tag/v0.5.0
+[0.4.0]: https://github.com/padobrik/a2a-spec/releases/tag/v0.4.0
+[0.3.2]: https://github.com/padobrik/a2a-spec/releases/tag/v0.3.2
+[0.3.1]: https://github.com/padobrik/a2a-spec/releases/tag/v0.3.1
+[0.3.0]: https://github.com/padobrik/a2a-spec/releases/tag/v0.3.0
+[0.2.0]: https://github.com/padobrik/a2a-spec/releases/tag/v0.2.0
+[0.1.0]: https://github.com/padobrik/a2a-spec/releases/tag/v0.1.0

agent_handshake-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to agent-handshake
+
+## Development setup
+
+```bash
+git clone https://github.com/padobrik/agent-handshake.git
+cd agent-handshake
+pip install -e ".[dev]"
+```
+
+To install optional extras for semantic and LangChain adapters:
+
+```bash
+pip install -e ".[dev,semantic,langchain]"
+```
+
+## Running the checks
+
+```bash
+# Tests
+pytest tests/
+
+# Lint + format
+ruff check src/ tests/
+ruff format src/ tests/
+
+# Type check
+mypy src/
+
+# All at once
+ruff check src/ tests/ && ruff format --check src/ tests/ && mypy src/ && pytest tests/
+```
+
+Pre-commit hooks (optional but recommended):
+
+```bash
+pre-commit install
+```
+
+## Pull request process
+
+1. Fork the repo and create a branch from `main`.
+2. Make your changes with tests covering new behaviour.
+3. Ensure all checks pass locally before pushing.
+4. Open a PR — the CI matrix (Python 3.11 / 3.12 / 3.13) must be green before merge.
+5. Keep PRs focused: one logical change per PR.
+
+## Commit style
+
+Use the imperative mood in the subject line (`add`, `fix`, `remove`, not `added`).
+Keep the subject under 72 characters. Reference issues with `Fixes #N` in the body.
+
+## Reporting bugs
+
+Open an issue using the **Bug report** template. Include a minimal reproducible example.
+
+## Proposing features
+
+Open an issue using the **Feature request** template before starting significant work,
+to avoid building something that won't be merged.