Metadata-Version: 2.4
Name: agent-readiness-insights-protocol
Version: 0.1.0
Summary: Shared schema, dataclasses, and version constants for the agent-readiness insights ecosystem.
Project-URL: Homepage, https://github.com/harrydaihaolin/agent-readiness-insights-protocol
Project-URL: Repository, https://github.com/harrydaihaolin/agent-readiness-insights-protocol
Project-URL: Bug Tracker, https://github.com/harrydaihaolin/agent-readiness-insights-protocol/issues
Author: agent-readiness contributors
License: MIT
License-File: LICENSE
Keywords: agent-readiness,agents,ai,rules,schema
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](https://github.com/harrydaihaolin/agent-readiness-rules) |
| Public scanner | [`agent-readiness`](https://github.com/harrydaihaolin/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

```bash
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`](https://github.com/harrydaihaolin/agent-readiness/blob/main/src/agent_readiness/models.py)).

The engine's `/healthz` reports both versions:

```json
{
  "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

```python
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

```bash
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
