agent-readiness-insights-protocol 0.1.0__tar.gz

agent_readiness_insights_protocol-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests tools
+      - name: Test
+        run: pytest tests/ -v
+      - name: Verify schema export is up to date
+        run: |
+          python tools/export_schema.py
+          if ! git diff --quiet schemas/rule.schema.json; then
+            echo "schemas/rule.schema.json is stale. Run 'make schema' and commit."
+            git diff schemas/rule.schema.json
+            exit 1
+          fi
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install --upgrade pip build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

agent_readiness_insights_protocol-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+.env
+.env.local
+.DS_Store
+*.log

agent_readiness_insights_protocol-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: detect-private-key
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]

agent_readiness_insights_protocol-0.1.0/AGENTS.md

@@ -0,0 +1,48 @@
+# Agent guide
+
+Conventions for AI coding agents working in this repository.
+
+## Canonical commands
+
+- Install dev deps: `make dev`
+- Run tests:        `make test`
+- Lint:             `make lint`
+- Regenerate schema: `make schema`
+- Build wheel:      `make build`
+
+The package is pure data + dataclasses. No CLI, no I/O, no network calls.
+Everything is JSON-serialisable via pydantic.
+
+## Source of truth
+
+- `src/agent_readiness_insights_protocol/version.py` — `PROTOCOL_VERSION`
+  and `RULES_VERSION`. These are the contract. Bump only on intentional
+  breaking changes; consumers will pin against them.
+- `src/agent_readiness_insights_protocol/models.py` — pydantic dataclasses.
+  Adding optional fields is non-breaking. Renaming or removing fields is
+  breaking.
+- `schemas/rule.schema.json` — generated from `models.Rule` via
+  `tools/export_schema.py`. Regenerate before commit if `Rule` changes.
+
+## Versioning rules (the only thing that really matters here)
+
+| Change | Version bump |
+|---|---|
+| Add optional field to a model | none |
+| Add new optional field to JSON response | none |
+| Rename / remove field | major (1 → 2) |
+| Change field type semantics | major |
+| Add new model | none |
+| Add new match type to `Rule.match.type` enum | minor at most; runtime should accept-and-skip-unknown |
+
+## Do-not-touch (without a clear reason)
+
+- `version.py` integers — coordinated bump only.
+- The `model_config` of `Rule` and friends — `extra="forbid"` keeps consumers
+  honest. Never relax to `"allow"` without a major version bump.
+
+## Style
+
+- Pydantic v2 only. No dataclasses, no attrs, no manual `__init__`.
+- Type-annotated, `from __future__ import annotations` at the top of modules.
+- One model per concept. Compose with other models, don't subclass.

agent_readiness_insights_protocol-0.1.0/CODEOWNERS

@@ -0,0 +1 @@
+* @harrydaihaolin

agent_readiness_insights_protocol-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Thanks for your interest. This is the protocol package — the smallest,
+most-stable repo in the agent-readiness ecosystem. Most changes here are
+deliberate and require coordination with downstream consumers.
+
+## Before opening a PR
+
+1. Read [`AGENTS.md`](./AGENTS.md) — especially the versioning rules table.
+2. Decide whether your change is breaking or non-breaking. If breaking,
+   we'll need to bump `PROTOCOL_VERSION` or `RULES_VERSION` and coordinate
+   with `agent-readiness`, `agent-readiness-rules`, and the engine.
+3. Run `make dev && make test && make lint`.
+4. If you touched `models.Rule`, run `make schema` and commit the regenerated
+   `schemas/rule.schema.json`.
+
+## What belongs here
+
+- Pydantic dataclasses shared by client + engine + rules + scanner.
+- Version constants.
+- JSON Schema exports.
+
+## What does not belong here
+
+- HTTP clients (live in `agent-readiness-pro`).
+- Match-type implementations (live in `agent-readiness/rules_eval` and the
+  engine).
+- Rule files (live in `agent-readiness-rules`).
+- Tests of downstream behavior (live in their respective repos).
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml`.
+2. `make build`.
+3. `twine upload dist/*` (or `uv publish`).
+4. Tag `git tag v$VERSION && git push --tags`.

agent_readiness_insights_protocol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-readiness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_readiness_insights_protocol-0.1.0/Makefile

@@ -0,0 +1,23 @@
+.PHONY: install dev test lint schema clean build
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+test:
+	PYTHONPATH=src python3 -m pytest tests/ -v
+
+lint:
+	ruff check src tests tools
+
+schema:
+	PYTHONPATH=src python3 tools/export_schema.py
+
+clean:
+	rm -rf build dist *.egg-info src/*.egg-info .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+build: clean schema
+	python3 -m build

agent_readiness_insights_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+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

agent_readiness_insights_protocol-0.1.0/README.md

@@ -0,0 +1,86 @@
+# 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

agent_readiness_insights_protocol-0.1.0/SECURITY.md

@@ -0,0 +1,16 @@
+# Security policy
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.x     | yes       |
+
+## Reporting a vulnerability
+
+Email security reports to the maintainers via GitHub Security Advisories
+on this repository. Do not open public issues for security problems.
+
+This package contains no I/O, no network calls, and no code execution —
+the attack surface is limited to deserialization of untrusted JSON via
+pydantic. We will respond to triaged reports within 7 days.

agent_readiness_insights_protocol-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-readiness-insights-protocol"
+version = "0.1.0"
+description = "Shared schema, dataclasses, and version constants for the agent-readiness insights ecosystem."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "agent-readiness contributors" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+keywords = ["ai", "agents", "agent-readiness", "rules", "schema"]
+dependencies = [
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/harrydaihaolin/agent-readiness-insights-protocol"
+Repository = "https://github.com/harrydaihaolin/agent-readiness-insights-protocol"
+"Bug Tracker" = "https://github.com/harrydaihaolin/agent-readiness-insights-protocol/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.4",
+    "build",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_readiness_insights_protocol"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"schemas/rule.schema.json" = "agent_readiness_insights_protocol/schemas/rule.schema.json"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = false
+ignore_missing_imports = true