agent-readiness-insights-protocol

Shared schema, dataclasses, and version constants for the agent-readiness insights ecosystem.

This is a tiny PyPI package that defines the contract between three independent consumers of the insights system:

Splitting the protocol out keeps each consumer honest about the contract, lets either side iterate behind versioned interfaces, and means the engine never has to install the full agent-readiness runtime to deserialize a JSON response.

Install

pip install agent-readiness-insights-protocol

Pydantic is the only runtime dependency.

What's inside

• Dataclasses — Rule, Insight, SearchHit, EvaluateRequest, EvaluateResponse, HealthResponse. All pydantic.BaseModel subclasses with strict JSON serializers.
• Version constants — two independent integers:
  • PROTOCOL_VERSION — JSON shapes for /evaluate, /insights/search, /healthz.
  • RULES_VERSION — YAML rule schema (match types, required fields).
• JSON Schema export — schemas/rule.schema.json is generated by tools/export_schema.py and committed so any consumer's CI can validate YAML rule files without importing Python.

Versioning rules

Bump only on breaking changes. Adding optional fields is non-breaking and does NOT bump either version (mirrors the existing convention in agent-readiness/src/agent_readiness/models.py).

The engine's /healthz reports both versions:

{
  "protocol_version": 1,
  "rules_version_supported": [1],
  "rules_pack_version_loaded": "1.0.0",
  "engine_version": "0.1.0"
}

A client refuses to call when protocol_version mismatches; logs a warning when a rules version it doesn't recognise appears.

Usage

from agent_readiness_insights_protocol import (
    PROTOCOL_VERSION,
    RULES_VERSION,
    Rule,
    EvaluateRequest,
    EvaluateResponse,
)

req = EvaluateRequest(repo_path="/path/to/repo", with_insights=True)
print(req.model_dump_json())

Develop

make dev      # pip install -e ".[dev]"
make test     # pytest
make lint     # ruff check
make schema   # regenerate schemas/rule.schema.json
make build    # build wheel + sdist

License

MIT