feed-protocol 0.2.0__tar.gz

feed_protocol-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aniku Gul IEng, MIET, IMechE, VCAT II, CAA
+
+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.

feed_protocol-0.2.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: feed-protocol
+Version: 0.2.0
+Summary: FEED — Format for Enforced Evidence-based Digestion. A self-bootstrapping document protocol that forces downstream LLMs to ground answers in cited evidence.
+Author: Aniku Gul IEng, MIET, IMechE, VCAT II, CAA
+License: MIT License
+        
+        Copyright (c) 2026 Aniku Gul IEng, MIET, IMechE, VCAT II, CAA
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/mrjesters/feed-protocol
+Project-URL: Spec, https://github.com/mrjesters/feed-protocol/blob/main/spec/feed-spec-v0.2.md
+Keywords: llm,rag,grounding,documents,protocol,feed,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: tagger
+Requires-Dist: anthropic>=0.40; extra == "tagger"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: anthropic>=0.40; extra == "dev"
+Dynamic: license-file
+
+# FEED — Format for Enforced Evidence-based Digestion
+
+> Make any document tell the AI reading it: **here's what matters, here's the
+> evidence, cite it or say you can't.**
+
+FEED is a plain-text convention you embed in a document so that any LLM — Copilot,
+ChatGPT, Claude, Gemini, a local model — grounds its answers in your evidence and
+cites it by ID. No install, no plugin, no provider support, no prior knowledge of
+FEED required on either side. It works on every model **today** because the
+document teaches the rules inline.
+
+It also has **teeth**: because evidence carries stable IDs and answers must cite
+them, you can *mechanically verify* that an answer is actually grounded.
+
+```
+┌─ Header ──────────────────────────────────────────────┐
+│ <!-- FEED:DOC version="0.2" grounding="strict" -->     │
+│ > AI INGESTION NOTICE … ground answers, cite [E###] …  │  ← teaches any LLM the rules
+├─ Tier 0: Claims & Decisions (front-loaded) ───────────┤  ← small-context-safe
+├─ Tier 1: Findings (narrative, references [E001]) ─────┤
+├─ Tier 2: Evidence (atomic key/value facts, IDs) ──────┤  ← the source of truth
+└────────────────────────────────────────────────────────┘
+```
+
+## Why it exists
+
+You generate AI reports and send them to people who paste them into their own AI.
+Every hop loses fidelity — the reader's AI skims headings and riffs. FEED fixes
+the **author** side of that loop: the document constrains how the downstream AI
+reads and answers. Nothing else does this at the document level (`llms.txt` is
+website-level and has no grounding contract; RAG/citation systems are all
+retrieval-side, controlled by the AI, not the author).
+
+## FEED is AI-to-AI (the library never needs its own API key)
+
+The AI **already in your loop** — the one that wrote the report, your assistant, a
+pipeline step — is what produces FEED. The library just renders, validates, and
+verifies; it never calls an LLM of its own. Authoring is self-bootstrapping, the
+same way ingestion is:
+
+```
+Reading side:   the document carries a notice that teaches any AI to ground & cite
+Authoring side: an authoring prompt + schema teach any AI to emit FEED, then
+                feed.build() renders it deterministically — no key, no network
+```
+
+### Primary flow: the AI emits FEED, you render it
+
+```python
+from feed import AUTHORING_PROMPT, FEED_JSON_SCHEMA, build
+
+# 1. Hand AUTHORING_PROMPT + FEED_JSON_SCHEMA to whatever AI is already in your loop.
+#    It returns structured JSON (no FEED tooling needed on the AI's side).
+# 2. Render that JSON into a validated FEED document — pure Python, no API key:
+doc = build(ai_json, grounding="strict", author="N. Gul")
+doc.write("report.md")
+```
+
+Or entirely from the shell:
+
+```bash
+feed prompt > authoring-kit.txt        # the prompt + schema to give any AI
+feed build ai_output.json -o report.md # render the AI's JSON into FEED (no key)
+```
+
+Manual additions are just edits: open `report.md` and add/adjust evidence and
+claims by hand — it's plain markdown. `feed validate` checks it's still conformant.
+
+> `feed tag draft.md` is an **optional** convenience that calls Claude directly,
+> for when you have a plain document and *no* AI already in the loop. It is not the
+> primary path and is the only thing that needs an API key.
+
+## Quick start
+
+### Build one in Python (manual / programmatic)
+
+```python
+from feed import FeedDocument
+
+doc = FeedDocument("Q2 Pump Health Assessment", grounding="strict")
+doc.add_evidence("E001", asset="XYZ-003", metric="vibration_rms",
+                 value="12.4 mm/s",
+                 threshold="11.2 mm/s (ISO 10816-3 Zone C)", confidence="high")
+doc.add_claim("C1", "XYZ-003 needs intervention", evidence=["E001"],
+              decision="Approve bearing replacement work order")
+
+doc.write("report.md")    # clean markdown, FEED in HTML comments
+doc.write("report.html")  # styled, opens in any browser
+```
+
+Your team opens `report.md` as a normal report. They upload it to whatever AI
+they use → it reads the notice, sees the evidence, and answers grounded.
+
+### Verify an answer was grounded (the teeth)
+
+```python
+from feed import FeedDocument, verify
+
+doc = FeedDocument.read("report.md")
+report = verify(ai_answer_text, doc)
+print(report.passed)   # False if it cited evidence that doesn't exist,
+                       # or (strict mode) didn't cite anything
+```
+
+### From the command line
+
+```bash
+feed prompt                                     # authoring kit for any AI (no key)
+feed build ai_output.json -o report.md          # render an AI's JSON into FEED (no key)
+feed validate report.md                         # is it well-formed FEED?
+feed verify --doc report.md --answer answer.txt # is this answer grounded?
+feed render report.md --to html -o report.html  # styled HTML
+feed tag draft.md --grounding strict -o report.md  # OPTIONAL: auto-tag via Claude (needs key)
+```
+
+## What's in this repo
+
+| Path | What it is |
+|------|------------|
+| `spec/feed-spec-v0.2.md` | The protocol definition (the constitution) |
+| `feed/` | The reference library — build, render, validate, verify, auto-tag |
+| `feed/verify.py` | The citation verifier — FEED's defensible edge, ~40 lines |
+| `feed/cli.py` | The `feed` command-line tool |
+| `examples/` | A complete worked example: a pump condition report (`.md` + `.html`) and the script that builds it |
+| `templates/blank.feed.md` | A hand-authoring starter |
+| `tests/` | Round-trip, validation, and verification tests |
+
+## Install
+
+```bash
+pip install -e .            # library + CLI, zero dependencies
+pip install -e ".[tagger]"  # adds the auto-tagger (needs anthropic + ANTHROPIC_API_KEY)
+```
+
+The core — authoring kit, build, render, validate, verify — is **pure Python with
+no dependencies and never calls an LLM**. Only the optional `tag` convenience
+calls Claude directly; it defaults to Claude Opus 4.8.
+
+## The three primitives
+
+- **Evidence** — atomic, ID'd, key/value facts. Never prose. The source of truth.
+- **Claim** — a short statement grounded in evidence IDs, optionally a decision.
+- **Header** — declares the grounding mode and carries the self-teaching notice.
+
+Plus **grounding modes** (`strict` / `standard` / `open`) — the author's dial for
+how strict the reading AI must be. In `strict`, no evidence means "Not supported
+by this document."
+
+## Status
+
+v0.2 — spec + reference library + verifier + CLI + auto-tagger + worked example.
+Deliberately out of scope for now: PDF/DOCX embedding, a hosted validator, and any
+provider-native "FEED mode".
+
+MIT licensed. Spec and tooling are open — adoption is the point.

feed_protocol-0.2.0/README.md

@@ -0,0 +1,155 @@
+# FEED — Format for Enforced Evidence-based Digestion
+
+> Make any document tell the AI reading it: **here's what matters, here's the
+> evidence, cite it or say you can't.**
+
+FEED is a plain-text convention you embed in a document so that any LLM — Copilot,
+ChatGPT, Claude, Gemini, a local model — grounds its answers in your evidence and
+cites it by ID. No install, no plugin, no provider support, no prior knowledge of
+FEED required on either side. It works on every model **today** because the
+document teaches the rules inline.
+
+It also has **teeth**: because evidence carries stable IDs and answers must cite
+them, you can *mechanically verify* that an answer is actually grounded.
+
+```
+┌─ Header ──────────────────────────────────────────────┐
+│ <!-- FEED:DOC version="0.2" grounding="strict" -->     │
+│ > AI INGESTION NOTICE … ground answers, cite [E###] …  │  ← teaches any LLM the rules
+├─ Tier 0: Claims & Decisions (front-loaded) ───────────┤  ← small-context-safe
+├─ Tier 1: Findings (narrative, references [E001]) ─────┤
+├─ Tier 2: Evidence (atomic key/value facts, IDs) ──────┤  ← the source of truth
+└────────────────────────────────────────────────────────┘
+```
+
+## Why it exists
+
+You generate AI reports and send them to people who paste them into their own AI.
+Every hop loses fidelity — the reader's AI skims headings and riffs. FEED fixes
+the **author** side of that loop: the document constrains how the downstream AI
+reads and answers. Nothing else does this at the document level (`llms.txt` is
+website-level and has no grounding contract; RAG/citation systems are all
+retrieval-side, controlled by the AI, not the author).
+
+## FEED is AI-to-AI (the library never needs its own API key)
+
+The AI **already in your loop** — the one that wrote the report, your assistant, a
+pipeline step — is what produces FEED. The library just renders, validates, and
+verifies; it never calls an LLM of its own. Authoring is self-bootstrapping, the
+same way ingestion is:
+
+```
+Reading side:   the document carries a notice that teaches any AI to ground & cite
+Authoring side: an authoring prompt + schema teach any AI to emit FEED, then
+                feed.build() renders it deterministically — no key, no network
+```
+
+### Primary flow: the AI emits FEED, you render it
+
+```python
+from feed import AUTHORING_PROMPT, FEED_JSON_SCHEMA, build
+
+# 1. Hand AUTHORING_PROMPT + FEED_JSON_SCHEMA to whatever AI is already in your loop.
+#    It returns structured JSON (no FEED tooling needed on the AI's side).
+# 2. Render that JSON into a validated FEED document — pure Python, no API key:
+doc = build(ai_json, grounding="strict", author="N. Gul")
+doc.write("report.md")
+```
+
+Or entirely from the shell:
+
+```bash
+feed prompt > authoring-kit.txt        # the prompt + schema to give any AI
+feed build ai_output.json -o report.md # render the AI's JSON into FEED (no key)
+```
+
+Manual additions are just edits: open `report.md` and add/adjust evidence and
+claims by hand — it's plain markdown. `feed validate` checks it's still conformant.
+
+> `feed tag draft.md` is an **optional** convenience that calls Claude directly,
+> for when you have a plain document and *no* AI already in the loop. It is not the
+> primary path and is the only thing that needs an API key.
+
+## Quick start
+
+### Build one in Python (manual / programmatic)
+
+```python
+from feed import FeedDocument
+
+doc = FeedDocument("Q2 Pump Health Assessment", grounding="strict")
+doc.add_evidence("E001", asset="XYZ-003", metric="vibration_rms",
+                 value="12.4 mm/s",
+                 threshold="11.2 mm/s (ISO 10816-3 Zone C)", confidence="high")
+doc.add_claim("C1", "XYZ-003 needs intervention", evidence=["E001"],
+              decision="Approve bearing replacement work order")
+
+doc.write("report.md")    # clean markdown, FEED in HTML comments
+doc.write("report.html")  # styled, opens in any browser
+```
+
+Your team opens `report.md` as a normal report. They upload it to whatever AI
+they use → it reads the notice, sees the evidence, and answers grounded.
+
+### Verify an answer was grounded (the teeth)
+
+```python
+from feed import FeedDocument, verify
+
+doc = FeedDocument.read("report.md")
+report = verify(ai_answer_text, doc)
+print(report.passed)   # False if it cited evidence that doesn't exist,
+                       # or (strict mode) didn't cite anything
+```
+
+### From the command line
+
+```bash
+feed prompt                                     # authoring kit for any AI (no key)
+feed build ai_output.json -o report.md          # render an AI's JSON into FEED (no key)
+feed validate report.md                         # is it well-formed FEED?
+feed verify --doc report.md --answer answer.txt # is this answer grounded?
+feed render report.md --to html -o report.html  # styled HTML
+feed tag draft.md --grounding strict -o report.md  # OPTIONAL: auto-tag via Claude (needs key)
+```
+
+## What's in this repo
+
+| Path | What it is |
+|------|------------|
+| `spec/feed-spec-v0.2.md` | The protocol definition (the constitution) |
+| `feed/` | The reference library — build, render, validate, verify, auto-tag |
+| `feed/verify.py` | The citation verifier — FEED's defensible edge, ~40 lines |
+| `feed/cli.py` | The `feed` command-line tool |
+| `examples/` | A complete worked example: a pump condition report (`.md` + `.html`) and the script that builds it |
+| `templates/blank.feed.md` | A hand-authoring starter |
+| `tests/` | Round-trip, validation, and verification tests |
+
+## Install
+
+```bash
+pip install -e .            # library + CLI, zero dependencies
+pip install -e ".[tagger]"  # adds the auto-tagger (needs anthropic + ANTHROPIC_API_KEY)
+```
+
+The core — authoring kit, build, render, validate, verify — is **pure Python with
+no dependencies and never calls an LLM**. Only the optional `tag` convenience
+calls Claude directly; it defaults to Claude Opus 4.8.
+
+## The three primitives
+
+- **Evidence** — atomic, ID'd, key/value facts. Never prose. The source of truth.
+- **Claim** — a short statement grounded in evidence IDs, optionally a decision.
+- **Header** — declares the grounding mode and carries the self-teaching notice.
+
+Plus **grounding modes** (`strict` / `standard` / `open`) — the author's dial for
+how strict the reading AI must be. In `strict`, no evidence means "Not supported
+by this document."
+
+## Status
+
+v0.2 — spec + reference library + verifier + CLI + auto-tagger + worked example.
+Deliberately out of scope for now: PDF/DOCX embedding, a hosted validator, and any
+provider-native "FEED mode".
+
+MIT licensed. Spec and tooling are open — adoption is the point.

feed_protocol-0.2.0/feed/__init__.py

@@ -0,0 +1,38 @@
+"""FEED — Format for Enforced Evidence-based Digestion.
+
+A self-bootstrapping document protocol that makes downstream LLMs ground their
+answers in cited evidence — and lets you mechanically verify they did.
+
+    from feed import FeedDocument
+
+    doc = FeedDocument("Q2 Pump Health Assessment", grounding="strict")
+    doc.add_evidence("E001", asset="XYZ-003", metric="vibration_rms",
+                     value="12.4 mm/s", threshold="11.2 mm/s (ISO 10816-3 Zone C)",
+                     confidence="high")
+    doc.add_claim("C1", "XYZ-003 needs intervention", evidence=["E001"],
+                  decision="Approve bearing replacement work order")
+    print(doc.render("md"))
+"""
+
+from .authoring import AUTHORING_PROMPT, FEED_JSON_SCHEMA, build
+from .constants import GROUNDING_MODES, VERSION
+from .document import Claim, Evidence, FeedDocument
+from .validate import ValidationReport, validate
+from .verify import VerificationReport, verify
+
+__version__ = VERSION
+
+__all__ = [
+    "FeedDocument",
+    "Evidence",
+    "Claim",
+    "build",
+    "AUTHORING_PROMPT",
+    "FEED_JSON_SCHEMA",
+    "validate",
+    "ValidationReport",
+    "verify",
+    "VerificationReport",
+    "GROUNDING_MODES",
+    "VERSION",
+]

feed_protocol-0.2.0/feed/authoring.py

@@ -0,0 +1,157 @@
+"""The authoring side of FEED — self-bootstrapping, no API key required.
+
+FEED is an AI-to-AI protocol. The AI that is *already in the loop* (the one that
+wrote the report, or the user's assistant, or a pipeline step) is what produces
+FEED — the library never needs its own LLM credentials.
+
+That works because the authoring rules are portable, exactly like the ingestion
+notice is portable on the reading side:
+
+  1. `AUTHORING_PROMPT` + `FEED_JSON_SCHEMA` — hand these to *any* AI and it emits
+     conformant FEED data. No FEED-specific tooling on the AI's side.
+  2. `build(data)` — a pure-Python, dependency-free renderer that turns that data
+     into a validated FEED document. No network, no key.
+
+The optional `feed.tagger` module is a convenience wrapper that calls Claude for
+people who don't already have an AI in the loop — it is not the primary path.
+"""
+
+from __future__ import annotations
+
+from .document import FeedDocument
+
+# The instruction block to give any AI so it authors FEED natively.
+AUTHORING_PROMPT = """\
+You are producing a FEED document (Format for Enforced Evidence-based Digestion).
+FEED separates a document so a downstream AI can answer questions grounded in cited
+evidence. Return ONLY JSON matching the provided schema. Structure the content as:
+
+- evidence: every concrete fact in the source, as an atomic key/value block. Never
+  prose. Each gets an id E001, E002, ... in document order. Normalise values: ISO
+  dates (YYYY-MM-DD), explicit units, consistent names. Include thresholds and
+  baselines as their own fields when present. `type` is one of data | quote | calc |
+  observation | reference | image; `confidence` is high | medium | low; `note` is an
+  optional one-line free-text aside ("" if none).
+- claims: short narrative statements (ids C1, C2, ...), each grounded in one or more
+  evidence ids. If a claim implies an action, put it in `decision` ("" if none).
+- findings: brief narrative paragraphs (1-3 sentences) that reference evidence inline
+  as [E001]. Say each fact once and reference it by id rather than repeating it.
+- title and summary: the document title and a one-sentence bottom line.
+
+Rules: extract every concrete fact as evidence; never invent facts; be dense (no
+filler, no repetition); keep ids sequential and in document order.
+"""
+
+# JSON Schema the AI should emit. Compatible with Anthropic structured outputs
+# (additionalProperties:false everywhere) but usable with any model — paste it
+# alongside AUTHORING_PROMPT.
+FEED_JSON_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "title": {"type": "string"},
+        "summary": {"type": "string"},
+        "evidence": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "type": {
+                        "type": "string",
+                        "enum": ["data", "quote", "calc", "observation", "reference", "image"],
+                    },
+                    "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
+                    "fields": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "key": {"type": "string"},
+                                "value": {"type": "string"},
+                            },
+                            "required": ["key", "value"],
+                            "additionalProperties": False,
+                        },
+                    },
+                    "note": {"type": "string"},
+                },
+                "required": ["id", "type", "confidence", "fields", "note"],
+                "additionalProperties": False,
+            },
+        },
+        "claims": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "text": {"type": "string"},
+                    "evidence": {"type": "array", "items": {"type": "string"}},
+                    "decision": {"type": "string"},
+                },
+                "required": ["id", "text", "evidence", "decision"],
+                "additionalProperties": False,
+            },
+        },
+        "findings": {"type": "array", "items": {"type": "string"}},
+    },
+    "required": ["title", "summary", "evidence", "claims", "findings"],
+    "additionalProperties": False,
+}
+
+
+def build(
+    data: dict,
+    title: str | None = None,
+    author: str | None = None,
+    grounding: str = "strict",
+    created: str | None = None,
+) -> FeedDocument:
+    """Render a FeedDocument from the structured data an AI produced. Pure Python,
+    no LLM call. `grounding`, `author`, `created` are author-policy overrides — they
+    are not the AI's to decide, so they come from the caller, not the data.
+
+    Resilient to imperfect AI output: claim references to non-existent evidence are
+    dropped, and evidence with no fields is skipped, so a slightly-off model
+    response still yields a valid document.
+    """
+    doc = FeedDocument(
+        title=title or data.get("title") or "Untitled",
+        author=author or data.get("author"),
+        grounding=grounding,
+        created=created or data.get("created"),
+        summary=data.get("summary") or None,
+    )
+    for ev in data.get("evidence", []):
+        fields = _fields(ev)
+        if not fields:
+            continue
+        doc.add_evidence(
+            ev["id"],
+            type=ev.get("type", "data"),
+            confidence=ev.get("confidence", "medium"),
+            note=(ev.get("note") or None),
+            **fields,
+        )
+    valid_ev = {e.id for e in doc.evidence}
+    for c in data.get("claims", []):
+        evidence = [e for e in c.get("evidence", []) if e in valid_ev]
+        doc.add_claim(
+            c["id"],
+            text=c["text"],
+            evidence=evidence,
+            decision=(c.get("decision") or None),
+        )
+    for f in data.get("findings", []):
+        if f and f.strip():
+            doc.add_finding(f)
+    return doc
+
+
+def _fields(ev: dict) -> dict[str, str]:
+    """Accept either the schema's [{key,value},...] form or a plain {key: value}
+    mapping, so a hand-authored or differently-shaped AI payload still works."""
+    raw = ev.get("fields", [])
+    if isinstance(raw, dict):
+        return {k: str(v) for k, v in raw.items() if k}
+    return {f["key"]: f["value"] for f in raw if isinstance(f, dict) and f.get("key")}