agent-readiness-insights-protocol 0.8.1

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

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:

Consumer	Repo
OSS rule pack	agent-readiness-rules
Public scanner	agent-readiness
Closed insights engine	(private)

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