Skip to content

feat: v0.10.0 — Vaara HTTP API + evidence export + Article 12 receipts #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vaaraio merged 5 commits into from
May 16, 2026
Merged

feat: v0.10.0 — Vaara HTTP API + evidence export + Article 12 receipts #75

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dc5dc50
feat: Vaara HTTP API v1 (kernel-as-callable, OPA-style schema)
vaaraio May 16, 2026
8beeb56
feat: auditor-facing article-evidence Markdown export
vaaraio May 16, 2026
cda379b
feat: Article 12 commit-prove receipt pair
vaaraio May 16, 2026
dbbfd9b
chore: release v0.10.0
vaaraio May 16, 2026
a05c60b
fix: drop unused imports flagged by ruff F401
vaaraio May 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,57 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht

## [Unreleased]

## [0.10.0] - 2026-05-16

**Theme: Vaara as the kernel others build around.** v0.10.0 ships the
network-callable surface, the auditor-facing evidence artefact, and the
offline-verifiable receipt pair. Each of the three pieces is additive
and backward-compatible; together they reposition Vaara from a Python
library to a runtime kernel that control planes, audit consumers, and
orchestration frameworks reference. The HTTP contract at
`docs/openapi.yaml` is versioned `/v1/` independently of the project
version, following the OPA pattern.

### Added
- **HTTP API reference server (`vaara[server]` extra).** Exposes the
conformal scorer and hash-chained audit trail over HTTP per the
contract in `docs/openapi.yaml`. Endpoints: `POST /v1/score`,
`POST /v1/score/outcome`, `POST /v1/audit/events`,
`GET /v1/audit/actions/{action_id}/chain`, `POST /v1/audit/verify`,
`GET /v1/server`, `GET /v1/health`. The spec is authoritative; the
reference server in `src/vaara/server/` is a FastAPI implementation
suitable for local development and modest production loads.
- **`vaara serve`** CLI subcommand.
- **OpenAPI 3.1 contract at `docs/openapi.yaml`.** Stable v1 surface,
intended as the integration point for control planes, orchestration
frameworks, and audit consumers. Vaara defines the interface; the
vendors call it.
- 11 new HTTP server tests (`tests/test_server.py`).
- **Auditor-facing evidence report rendering.** New module
`vaara.compliance.render` with `render_markdown`, `render_json`, and
`render_narrative` for the `ConformityReport` produced by
`ComplianceEngine.assess`. Markdown output has per-domain article
tables, per-article detail sections, evidence status badges,
audit-chain integrity flagging, and a deployer-owns-the-decision
disclaimer suitable for shipping to a regulator or attaching to an
internal conformity submission.
- **`vaara compliance report --db PATH --format md|json|narrative
[--out FILE]`** CLI subcommand. Loads an audit SQLite DB, runs
`ComplianceEngine.assess`, renders to chosen format.
- 5 new compliance-render tests (`tests/test_compliance_render.py`).
- **Article 12 commit-prove receipt pair.** New module
`vaara.audit.receipts` derives an offline-verifiable receipt from the
existing audit chain: a `commit_hash` covering the gate-time decision
(action_id, decision, risk_score, thresholds, decided_at) and an
`outcome_hash` covering the post-execution outcome and embedding the
commit_hash. Open-standards SHA-256 over canonical JSON, no external
cryptography library required. Verification needs only `hashlib`,
enabling per-action handoff to auditors without sharing the full chain
or key material.
- **`vaara trail receipt --db PATH --action-id ID [--out FILE]`** CLI
subcommand. Extracts and verifies the receipt pair, prints JSON.
- 11 new receipt tests (`tests/test_receipts.py`).

## [0.9.0] - 2026-05-15

**Theme: policy artifact validate + test framework.** v0.9.0 ships the
Expand Down
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,23 @@ else:

`report_outcome` closes the loop. MWU reweights signals based on which ones predicted the outcome.

## HTTP API

The same scorer and audit trail are available over HTTP for non-Python agents and for control planes that prefer a network boundary. Install with the `server` extra:

```
pip install 'vaara[server]'
vaara serve --host 0.0.0.0 --port 8000
```

```
curl -sX POST http://localhost:8000/v1/score \
-H 'content-type: application/json' \
-d '{"tool_name":"tx.transfer","agent_id":"agent-007","base_risk_score":0.5}'
```
Comment on lines +62 to +71

@coderabbitai coderabbitai Bot May 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language identifiers to new fenced code blocks.

The new blocks are missing fence languages (bash), which triggers MD040 and reduces syntax highlighting quality.

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 62-62: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

[warning] 67-67: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 62 - 71, The README's new fenced code blocks lack
language identifiers causing MD040; update the two blocks that contain the
pip/vaara serve snippet (pip install 'vaara[server]' and vaara serve --host ...)
and the curl POST snippet (curl -sX POST ... -d
'{"tool_name":"tx.transfer","agent_id":"agent-007","base_risk_score":0.5}') by
adding the bash fence marker (```bash) at the start of each block so they are
properly highlighted and pass the linter.


The contract is in [docs/openapi.yaml](docs/openapi.yaml). Vaara defines the interface; control-plane and orchestration vendors call it. Integration recipes for adopters live under `examples/recipes/`.

## Where things live

- [docs/formal_specification.md](docs/formal_specification.md): math. MWU regret bound O(sqrt(T log N)), conformal coverage guarantees, security properties.
Expand Down
Loading
Loading