pyucp 0.1.0__tar.gz

pyucp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

pyucp-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: pyucp
+Version: 0.1.0
+Summary: Universal Context Package (UCP) — reference library: validation, typed models, canonical LLM rendering
+Project-URL: Specification, https://github.com/contextos/ucp
+Author: Context OS Team
+License-Expression: Apache-2.0
+Keywords: context,context-engineering,llm,mcp,ucp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ucp — Universal Context Package reference library (Python)
+
+Reference implementation of the [UCP specification](../../specs/ucp/SPEC.md)
+(v0.1.0-draft): schema validation, typed Pydantic models, and canonical
+CommonMark rendering for LLM prompts with token budgeting.
+
+```bash
+pip install pyucp   # distribution "pyucp", import name "ucp"
+```
+
+## Quickstart
+
+```python
+import ucp
+
+# Load and validate a package (raises ucp.UCPValidationError on failure)
+pkg = ucp.load("task.ucp.json")
+
+print(pkg.entity.title)
+print(pkg.must_know[0].text)
+
+# Canonical prompt rendering (SPEC §7.1)
+prompt = ucp.render(pkg)
+
+# Under a token budget: truncates by ascending salience, drops sections
+# in the order defined by SPEC §7.2 (summary/conflicts/diff survive longest)
+prompt = ucp.render(pkg, token_budget=1500)
+
+# Validation without parsing into models
+errors = ucp.iter_errors({"ucp_version": "0.1.0"})  # -> list of messages
+
+# Referential integrity (ucp-core profile): every claim source key must exist
+dangling = pkg.verify_references()  # -> [] when clean
+```
+
+## What this library guarantees
+
+- **Schema validation** against the bundled JSON Schema (draft 2020-12),
+  identical to `specs/ucp/schema/ucp.schema.json`.
+- **Must-ignore semantics**: unknown fields are preserved, never rejected
+  (SPEC §6.1) — models use `extra="allow"`.
+- **Provenance enforcement**: a claim without sources fails both schema
+  validation and model parsing.
+- **Deterministic rendering**: the same package always renders to the same
+  prompt, so downstream LLM behavior is reproducible.
+
+Token counting uses a fast `len(text) / 4` heuristic; pass your own counter
+via `render(pkg, token_budget=..., count_tokens=fn)` for exact budgets.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against the spec's `examples/` and `conformance/` suites when the
+repository layout is available.

pyucp-0.1.0/README.md

@@ -0,0 +1,58 @@
+# ucp — Universal Context Package reference library (Python)
+
+Reference implementation of the [UCP specification](../../specs/ucp/SPEC.md)
+(v0.1.0-draft): schema validation, typed Pydantic models, and canonical
+CommonMark rendering for LLM prompts with token budgeting.
+
+```bash
+pip install pyucp   # distribution "pyucp", import name "ucp"
+```
+
+## Quickstart
+
+```python
+import ucp
+
+# Load and validate a package (raises ucp.UCPValidationError on failure)
+pkg = ucp.load("task.ucp.json")
+
+print(pkg.entity.title)
+print(pkg.must_know[0].text)
+
+# Canonical prompt rendering (SPEC §7.1)
+prompt = ucp.render(pkg)
+
+# Under a token budget: truncates by ascending salience, drops sections
+# in the order defined by SPEC §7.2 (summary/conflicts/diff survive longest)
+prompt = ucp.render(pkg, token_budget=1500)
+
+# Validation without parsing into models
+errors = ucp.iter_errors({"ucp_version": "0.1.0"})  # -> list of messages
+
+# Referential integrity (ucp-core profile): every claim source key must exist
+dangling = pkg.verify_references()  # -> [] when clean
+```
+
+## What this library guarantees
+
+- **Schema validation** against the bundled JSON Schema (draft 2020-12),
+  identical to `specs/ucp/schema/ucp.schema.json`.
+- **Must-ignore semantics**: unknown fields are preserved, never rejected
+  (SPEC §6.1) — models use `extra="allow"`.
+- **Provenance enforcement**: a claim without sources fails both schema
+  validation and model parsing.
+- **Deterministic rendering**: the same package always renders to the same
+  prompt, so downstream LLM behavior is reproducible.
+
+Token counting uses a fast `len(text) / 4` heuristic; pass your own counter
+via `render(pkg, token_budget=..., count_tokens=fn)` for exact budgets.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Tests run against the spec's `examples/` and `conformance/` suites when the
+repository layout is available.

pyucp-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# Distribution name is "pyucp" ("ucp" is taken on PyPI by an SMS protocol
+# wrapper); the import name remains "ucp".
+name = "pyucp"
+version = "0.1.0"
+description = "Universal Context Package (UCP) — reference library: validation, typed models, canonical LLM rendering"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "Context OS Team" }]
+keywords = ["ucp", "llm", "context", "context-engineering", "mcp"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "pydantic>=2.7",
+  "jsonschema>=4.21",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Specification = "https://github.com/contextos/ucp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ucp"]

pyucp-0.1.0/src/ucp/__init__.py

@@ -0,0 +1,86 @@
+"""ucp — reference library for the Universal Context Package specification.
+
+Spec: https://github.com/contextos/ucp (v0.1.0-draft)
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Union
+
+from .models import (
+    AccessControl,
+    Actor,
+    Audience,
+    Budget,
+    Change,
+    Claim,
+    Conflict,
+    ConflictPosition,
+    ContextDiff,
+    Decision,
+    Entity,
+    EntityRef,
+    Event,
+    Generator,
+    Package,
+    RelatedObject,
+    Source,
+    Summary,
+)
+from .render import estimate_tokens, render
+from .validation import UCPValidationError, iter_errors, schema, validate
+
+__version__ = "0.1.0"
+
+SPEC_VERSION = "0.1.0"
+
+
+def loads(text: str, *, validate_schema: bool = True) -> Package:
+    """Parse a UCP document from a JSON string."""
+    data = json.loads(text)
+    if validate_schema:
+        validate(data)
+    return Package.model_validate(data)
+
+
+def load(path: Union[str, Path], *, validate_schema: bool = True) -> Package:
+    """Load a UCP document from a ``.ucp.json`` file."""
+    return loads(Path(path).read_text(encoding="utf-8"), validate_schema=validate_schema)
+
+
+def dumps(pkg: Package, *, indent: int = 2) -> str:
+    """Serialize a package back to JSON (unknown fields preserved)."""
+    return pkg.model_dump_json(indent=indent, exclude_none=True, by_alias=True)
+
+
+__all__ = [
+    "SPEC_VERSION",
+    "AccessControl",
+    "Actor",
+    "Audience",
+    "Budget",
+    "Change",
+    "Claim",
+    "Conflict",
+    "ConflictPosition",
+    "ContextDiff",
+    "Decision",
+    "Entity",
+    "EntityRef",
+    "Event",
+    "Generator",
+    "Package",
+    "RelatedObject",
+    "Source",
+    "Summary",
+    "UCPValidationError",
+    "dumps",
+    "estimate_tokens",
+    "iter_errors",
+    "load",
+    "loads",
+    "render",
+    "schema",
+    "validate",
+]

pyucp-0.1.0/src/ucp/models.py

@@ -0,0 +1,210 @@
+"""Typed models for Universal Context Packages (SPEC §4).
+
+All models tolerate unknown fields (``extra="allow"``) to honor the
+must-ignore rule (SPEC §6.1): a package produced by a newer spec version
+must parse, with unknown fields preserved on the model instance.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _UCPModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class Actor(_UCPModel):
+    id: str
+    display_name: Optional[str] = None
+    role: Optional[str] = None
+
+
+class Generator(_UCPModel):
+    name: str
+    version: Optional[str] = None
+    url: Optional[str] = None
+
+
+class EntityRef(_UCPModel):
+    system: str
+    type: str
+    id: str
+    url: Optional[str] = None
+
+
+class Entity(_UCPModel):
+    ref: EntityRef
+    title: str
+    status: Optional[str] = None
+    assignee: Optional[Actor] = None
+    attributes: Optional[dict[str, Any]] = None
+
+
+class Summary(_UCPModel):
+    text: str
+    sources: list[str] = Field(default_factory=list)
+    confidence: Optional[float] = Field(default=None, ge=0, le=1)
+
+
+class Claim(_UCPModel):
+    id: str
+    text: str
+    sources: list[str] = Field(min_length=1)
+    kind: Optional[str] = None
+    salience: Optional[float] = Field(default=None, ge=0, le=1)
+    confidence: Optional[float] = Field(default=None, ge=0, le=1)
+    asserted_at: Optional[datetime] = None
+    valid_from: Optional[datetime] = None
+    valid_to: Optional[datetime] = None
+    tags: list[str] = Field(default_factory=list)
+
+
+class Decision(_UCPModel):
+    id: str
+    decision: str
+    status: Literal["proposed", "accepted", "superseded", "rejected"]
+    sources: list[str] = Field(min_length=1)
+    rationale: Optional[str] = None
+    decided_by: Optional[Actor] = None
+    decided_at: Optional[datetime] = None
+    supersedes: Optional[str] = None
+
+
+class ConflictPosition(_UCPModel):
+    claim: str
+    sources: list[str] = Field(min_length=1)
+    asserted_at: Optional[datetime] = None
+
+
+class Conflict(_UCPModel):
+    id: str
+    description: str
+    positions: list[ConflictPosition] = Field(min_length=2)
+    resolution_hint: Optional[str] = None
+    severity: Optional[Literal["low", "medium", "high"]] = None
+
+
+class Change(_UCPModel):
+    type: Literal["added", "updated", "removed", "status_changed"]
+    summary: str
+    target: Optional[str] = None
+    occurred_at: Optional[datetime] = None
+    actor: Optional[Actor] = None
+    sources: list[str] = Field(default_factory=list)
+
+
+class ContextDiff(_UCPModel):
+    since: datetime
+    changes: list[Change]
+    baseline: Optional[str] = None
+
+
+class Event(_UCPModel):
+    occurred_at: datetime
+    summary: str
+    actor: Optional[Actor] = None
+    sources: list[str] = Field(default_factory=list)
+
+
+class RelatedObject(_UCPModel):
+    ref: EntityRef
+    title: str
+    relation: Optional[str] = None
+    salience: Optional[float] = Field(default=None, ge=0, le=1)
+    reason: Optional[str] = None
+
+
+class Source(_UCPModel):
+    system: str
+    type: str
+    title: str
+    url: Optional[str] = None
+    author: Optional[Actor] = None
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    content_hash: Optional[str] = None
+    retrieved_at: Optional[datetime] = None
+    trust: Optional[float] = Field(default=None, ge=0, le=1)
+    excerpt: Optional[str] = None
+
+
+class AccessControl(_UCPModel):
+    enforced: bool
+    mechanism: Optional[str] = None
+    checked_at: Optional[datetime] = None
+    audit_ref: Optional[str] = None
+
+
+class Audience(_UCPModel):
+    principal: Actor
+    access_control: Optional[AccessControl] = None
+
+
+class Budget(_UCPModel):
+    token_estimate: Optional[int] = Field(default=None, ge=0)
+
+
+class Package(_UCPModel):
+    ucp_version: str
+    id: str
+    generated_at: datetime
+    generator: Generator
+    entity: Entity
+    sources: dict[str, Source] = Field(min_length=1)
+
+    profiles: list[str] = Field(default_factory=list)
+    language: Optional[str] = None
+    audience: Optional[Audience] = None
+    situation: Optional[str] = None
+    summary: Optional[Summary] = None
+    must_know: list[Claim] = Field(default_factory=list)
+    constraints: list[Claim] = Field(default_factory=list)
+    risks: list[Claim] = Field(default_factory=list)
+    recommended_actions: list[Claim] = Field(default_factory=list)
+    decisions: list[Decision] = Field(default_factory=list)
+    conflicts: list[Conflict] = Field(default_factory=list)
+    context_diff: Optional[ContextDiff] = None
+    history: list[Event] = Field(default_factory=list)
+    dependencies: list[EntityRef] = Field(default_factory=list)
+    related_objects: list[RelatedObject] = Field(default_factory=list)
+    budget: Optional[Budget] = None
+    extensions: dict[str, Any] = Field(default_factory=dict)
+
+    def verify_references(self) -> list[str]:
+        """Return dangling source keys referenced anywhere in the package.
+
+        The ucp-core profile requires every referenced key to exist in the
+        ``sources`` registry. An empty list means the package is clean.
+        """
+        known = set(self.sources)
+        dangling: list[str] = []
+
+        def collect(keys: list[str], where: str) -> None:
+            for key in keys:
+                if key not in known:
+                    dangling.append(f"{where}: {key}")
+
+        if self.summary:
+            collect(self.summary.sources, "summary")
+        for section_name in ("must_know", "constraints", "risks", "recommended_actions"):
+            for claim in getattr(self, section_name):
+                collect(claim.sources, f"{section_name}[{claim.id}]")
+        for decision in self.decisions:
+            collect(decision.sources, f"decisions[{decision.id}]")
+        for conflict in self.conflicts:
+            for i, position in enumerate(conflict.positions):
+                collect(position.sources, f"conflicts[{conflict.id}].positions[{i}]")
+        if self.context_diff:
+            for i, change in enumerate(self.context_diff.changes):
+                collect(change.sources, f"context_diff.changes[{i}]")
+        for i, event in enumerate(self.history):
+            collect(event.sources, f"history[{i}]")
+        return dangling
+
+    def render(self, token_budget: Optional[int] = None, **kwargs: Any) -> str:
+        from .render import render
+
+        return render(self, token_budget=token_budget, **kwargs)

pyucp-0.1.0/src/ucp/render.py

@@ -0,0 +1,185 @@
+"""Canonical CommonMark rendering of a UCP package (SPEC §7).
+
+The rendering is deterministic: the same package always produces the same
+prompt. Under a token budget, items are dropped in ascending-salience order
+within sections, and sections are dropped in the order of SPEC §7.2 —
+``summary``, ``conflicts``, and ``context_diff`` survive longest.
+"""
+from __future__ import annotations
+
+import math
+from copy import deepcopy
+from datetime import datetime
+from typing import Callable, Optional
+
+from .models import Claim, Package, Source
+
+# Sections whose items may be dropped under a token budget, cheapest first.
+DROP_ORDER = (
+    "history",
+    "related_objects",
+    "recommended_actions",
+    "risks",
+    "constraints",
+    "decisions",
+    "must_know",
+)
+
+_SECTION_TITLES = {
+    "must_know": "Must know",
+    "constraints": "Constraints",
+    "risks": "Risks",
+    "recommended_actions": "Recommended actions",
+}
+
+
+def estimate_tokens(text: str) -> int:
+    """Fast token estimate (~4 chars per token). Good enough for budgeting."""
+    return max(1, math.ceil(len(text) / 4))
+
+
+def _date(dt: Optional[datetime]) -> str:
+    return dt.strftime("%Y-%m-%d") if dt else ""
+
+
+def _source_labels(keys: list[str], sources: dict[str, Source]) -> str:
+    titles = [sources[k].title if k in sources else k for k in keys]
+    return ", ".join(titles)
+
+
+def _claim_line(claim: Claim, sources: dict[str, Source]) -> str:
+    label = _source_labels(claim.sources, sources)
+    return f"- {claim.text} [source: {label}]"
+
+
+def _by_salience_desc(items: list) -> list:
+    """Descending salience; unspecified salience sorts last, original order kept.
+
+    Works for any item type: models without a salience field (e.g. Event)
+    are treated as unspecified.
+    """
+
+    def salience(item) -> float:
+        value = getattr(item, "salience", None)
+        return value if value is not None else -1.0
+
+    return sorted(enumerate(items), key=lambda pair: (-salience(pair[1]), pair[0]))
+
+
+def _render(pkg: Package) -> str:
+    src = pkg.sources
+    out: list[str] = []
+
+    ref = pkg.entity.ref
+    out.append(f"# Context: {pkg.entity.title}")
+    ref_line = f"> {ref.system}/{ref.type} {ref.id}"
+    if ref.url:
+        ref_line += f" — {ref.url}"
+    out.append(ref_line)
+    if pkg.entity.status:
+        out.append(f"> Status: {pkg.entity.status}")
+    out.append("")
+
+    if pkg.context_diff is not None:
+        out.append("## What changed")
+        out.append(f"Since {_date(pkg.context_diff.since)}:")
+        if pkg.context_diff.changes:
+            for change in pkg.context_diff.changes:
+                when = f"[{_date(change.occurred_at)}] " if change.occurred_at else ""
+                out.append(f"- {when}{change.summary}")
+        else:
+            out.append("- Nothing changed.")
+        out.append("")
+
+    if pkg.summary:
+        out.append("## Summary")
+        out.append(pkg.summary.text)
+        out.append("")
+
+    for field in ("must_know", "constraints", "risks"):
+        claims: list[Claim] = getattr(pkg, field)
+        if claims:
+            out.append(f"## {_SECTION_TITLES[field]}")
+            for _, claim in _by_salience_desc(claims):
+                out.append(_claim_line(claim, src))
+            out.append("")
+
+    if pkg.decisions:
+        out.append("## Decisions")
+        for decision in pkg.decisions:
+            line = f"- {decision.decision}"
+            if decision.rationale:
+                line += f" — {decision.rationale}"
+            meta = decision.status + (f", {_date(decision.decided_at)}" if decision.decided_at else "")
+            out.append(f"{line} ({meta})")
+        out.append("")
+
+    if pkg.conflicts:
+        out.append("## Conflicts")
+        for conflict in pkg.conflicts:
+            out.append(f"- {conflict.description}")
+            for position in conflict.positions:
+                when = f" ({_date(position.asserted_at)})" if position.asserted_at else ""
+                label = _source_labels(position.sources, src)
+                out.append(f"  - {position.claim}{when} [source: {label}]")
+            if conflict.resolution_hint:
+                out.append(f"  - Hint: {conflict.resolution_hint}")
+        out.append("")
+
+    if pkg.recommended_actions:
+        out.append(f"## {_SECTION_TITLES['recommended_actions']}")
+        for _, claim in _by_salience_desc(pkg.recommended_actions):
+            out.append(_claim_line(claim, src))
+        out.append("")
+
+    if pkg.history:
+        out.append("## Timeline")
+        for event in sorted(pkg.history, key=lambda e: e.occurred_at):
+            out.append(f"- [{_date(event.occurred_at)}] {event.summary}")
+        out.append("")
+
+    if pkg.related_objects:
+        out.append("## Related")
+        for _, related in _by_salience_desc(pkg.related_objects):
+            line = f"- {related.title}"
+            if related.relation:
+                line += f" ({related.relation})"
+            if related.reason:
+                line += f" — {related.reason}"
+            out.append(line)
+        out.append("")
+
+    out.append("## Sources")
+    for i, (key, source) in enumerate(pkg.sources.items(), start=1):
+        line = f"{i}. {source.title}"
+        if source.url:
+            line += f" — {source.url}"
+        out.append(line)
+
+    return "\n".join(out).strip() + "\n"
+
+
+def render(
+    pkg: Package,
+    token_budget: Optional[int] = None,
+    count_tokens: Callable[[str], int] = estimate_tokens,
+) -> str:
+    """Render a package to canonical CommonMark, optionally under a token budget."""
+    text = _render(pkg)
+    if token_budget is None or count_tokens(text) <= token_budget:
+        return text
+
+    trimmed = deepcopy(pkg)
+    for section in DROP_ORDER:
+        while getattr(trimmed, section):
+            # Drop the least salient item (ascending salience = end of the
+            # descending-ordered list, which is also the render order).
+            ordered = [item for _, item in _by_salience_desc(getattr(trimmed, section))]
+            ordered.pop()
+            setattr(trimmed, section, ordered)
+            text = _render(trimmed)
+            if count_tokens(text) <= token_budget:
+                return text
+    # Budget cannot be met by dropping optional sections; the protected core
+    # (summary, conflicts, context_diff) is returned as-is by design.
+    return text

pyucp-0.1.0/src/ucp/schema/ucp.schema.json

@@ -0,0 +1,301 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://spec.contextos.ai/ucp/0.1/ucp.schema.json",
+  "title": "Universal Context Package",
+  "description": "An open format for packaging task context for LLMs: claim-based, provenance-mandatory, time-aware, permission-aware. See SPEC.md for normative text.",
+  "type": "object",
+  "required": ["ucp_version", "id", "generated_at", "generator", "entity", "sources"],
+  "properties": {
+    "ucp_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$",
+      "description": "Semver of the UCP spec this package conforms to."
+    },
+    "id": {
+      "type": "string",
+      "format": "uri",
+      "description": "Globally unique package identifier. urn:uuid: recommended."
+    },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "generator": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Conformance profiles claimed, e.g. ucp-core, ucp-temporal, ucp-secure."
+    },
+    "language": {
+      "type": "string",
+      "description": "BCP 47 language tag of the textual content."
+    },
+    "audience": { "$ref": "#/$defs/Audience" },
+    "entity": { "$ref": "#/$defs/Entity" },
+    "situation": {
+      "type": "string",
+      "description": "One line: why this package was assembled."
+    },
+    "summary": { "$ref": "#/$defs/Summary" },
+    "must_know": { "type": "array", "items": { "$ref": "#/$defs/Claim" } },
+    "constraints": { "type": "array", "items": { "$ref": "#/$defs/Claim" } },
+    "risks": { "type": "array", "items": { "$ref": "#/$defs/Claim" } },
+    "recommended_actions": { "type": "array", "items": { "$ref": "#/$defs/Claim" } },
+    "decisions": { "type": "array", "items": { "$ref": "#/$defs/Decision" } },
+    "conflicts": { "type": "array", "items": { "$ref": "#/$defs/Conflict" } },
+    "context_diff": { "$ref": "#/$defs/ContextDiff" },
+    "history": { "type": "array", "items": { "$ref": "#/$defs/Event" } },
+    "dependencies": { "type": "array", "items": { "$ref": "#/$defs/EntityRef" } },
+    "related_objects": { "type": "array", "items": { "$ref": "#/$defs/RelatedObject" } },
+    "sources": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/Source" },
+      "description": "Provenance registry. Keys are package-local identifiers."
+    },
+    "budget": {
+      "type": "object",
+      "properties": {
+        "token_estimate": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)+$",
+        "description": "Reverse-DNS namespaced extension keys."
+      },
+      "description": "Producer-specific data. Must not alter the meaning of standard fields."
+    }
+  },
+  "$defs": {
+    "EntityRef": {
+      "type": "object",
+      "required": ["system", "type", "id"],
+      "properties": {
+        "system": {
+          "type": "string",
+          "description": "Source system, lowercase. Open vocabulary: jira, confluence, github, gitlab, gdrive, slack, email, bitrix24, 1c, filesystem, custom."
+        },
+        "type": {
+          "type": "string",
+          "description": "Object type within the system. Open vocabulary: issue, page, pull_request, file, message, record."
+        },
+        "id": { "type": "string" },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "Entity": {
+      "type": "object",
+      "required": ["ref", "title"],
+      "properties": {
+        "ref": { "$ref": "#/$defs/EntityRef" },
+        "title": { "type": "string" },
+        "status": { "type": "string" },
+        "assignee": { "$ref": "#/$defs/Actor" },
+        "attributes": {
+          "type": "object",
+          "description": "System-specific fields, non-normative."
+        }
+      }
+    },
+    "Actor": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string" },
+        "display_name": { "type": "string" },
+        "role": { "type": "string" }
+      }
+    },
+    "Summary": {
+      "type": "object",
+      "required": ["text"],
+      "properties": {
+        "text": { "type": "string", "description": "Plain text or CommonMark." },
+        "sources": { "$ref": "#/$defs/SourceKeys" },
+        "confidence": { "$ref": "#/$defs/UnitInterval" }
+      }
+    },
+    "Claim": {
+      "type": "object",
+      "required": ["id", "text", "sources"],
+      "properties": {
+        "id": { "type": "string" },
+        "text": { "type": "string", "description": "Plain text or CommonMark." },
+        "kind": {
+          "type": "string",
+          "description": "Open vocabulary: fact, instruction, warning, assumption."
+        },
+        "salience": { "$ref": "#/$defs/UnitInterval" },
+        "confidence": { "$ref": "#/$defs/UnitInterval" },
+        "sources": { "$ref": "#/$defs/SourceKeysRequired" },
+        "asserted_at": { "type": "string", "format": "date-time" },
+        "valid_from": { "type": "string", "format": "date-time" },
+        "valid_to": {
+          "oneOf": [
+            { "type": "string", "format": "date-time" },
+            { "type": "null" }
+          ],
+          "description": "null or absent means currently valid."
+        },
+        "tags": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "Decision": {
+      "type": "object",
+      "required": ["id", "decision", "status", "sources"],
+      "properties": {
+        "id": { "type": "string" },
+        "decision": { "type": "string" },
+        "rationale": { "type": "string" },
+        "status": { "enum": ["proposed", "accepted", "superseded", "rejected"] },
+        "decided_by": { "$ref": "#/$defs/Actor" },
+        "decided_at": { "type": "string", "format": "date-time" },
+        "supersedes": { "type": "string", "description": "id of an earlier decision." },
+        "sources": { "$ref": "#/$defs/SourceKeysRequired" }
+      }
+    },
+    "Conflict": {
+      "type": "object",
+      "required": ["id", "description", "positions"],
+      "properties": {
+        "id": { "type": "string" },
+        "description": { "type": "string" },
+        "positions": {
+          "type": "array",
+          "minItems": 2,
+          "items": {
+            "type": "object",
+            "required": ["claim", "sources"],
+            "properties": {
+              "claim": { "type": "string" },
+              "sources": { "$ref": "#/$defs/SourceKeysRequired" },
+              "asserted_at": { "type": "string", "format": "date-time" }
+            }
+          }
+        },
+        "resolution_hint": { "type": "string" },
+        "severity": { "enum": ["low", "medium", "high"] }
+      }
+    },
+    "ContextDiff": {
+      "type": "object",
+      "required": ["since", "changes"],
+      "properties": {
+        "since": { "type": "string", "format": "date-time" },
+        "baseline": {
+          "type": "string",
+          "description": "Open vocabulary: last_view, last_package, explicit."
+        },
+        "changes": {
+          "type": "array",
+          "description": "Empty array is meaningful: nothing changed.",
+          "items": {
+            "type": "object",
+            "required": ["type", "summary"],
+            "properties": {
+              "type": { "enum": ["added", "updated", "removed", "status_changed"] },
+              "target": {
+                "type": "string",
+                "description": "Open vocabulary: document, comment, field, decision, risk, dependency."
+              },
+              "summary": { "type": "string" },
+              "occurred_at": { "type": "string", "format": "date-time" },
+              "actor": { "$ref": "#/$defs/Actor" },
+              "sources": { "$ref": "#/$defs/SourceKeys" }
+            }
+          }
+        }
+      }
+    },
+    "Event": {
+      "type": "object",
+      "required": ["occurred_at", "summary"],
+      "properties": {
+        "occurred_at": { "type": "string", "format": "date-time" },
+        "summary": { "type": "string" },
+        "actor": { "$ref": "#/$defs/Actor" },
+        "sources": { "$ref": "#/$defs/SourceKeys" }
+      }
+    },
+    "RelatedObject": {
+      "type": "object",
+      "required": ["ref", "title"],
+      "properties": {
+        "ref": { "$ref": "#/$defs/EntityRef" },
+        "title": { "type": "string" },
+        "relation": {
+          "type": "string",
+          "description": "Open vocabulary: blocks, blocked_by, supersedes, implements, mentions, similar."
+        },
+        "salience": { "$ref": "#/$defs/UnitInterval" },
+        "reason": {
+          "type": "string",
+          "description": "Human-readable: why this object is in the package."
+        }
+      }
+    },
+    "Source": {
+      "type": "object",
+      "required": ["system", "type", "title"],
+      "properties": {
+        "system": { "type": "string" },
+        "type": { "type": "string" },
+        "title": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "author": { "$ref": "#/$defs/Actor" },
+        "created_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "SHA-256 of the content as retrieved, for integrity verification."
+        },
+        "retrieved_at": { "type": "string", "format": "date-time" },
+        "trust": { "$ref": "#/$defs/UnitInterval" },
+        "excerpt": { "type": "string" }
+      }
+    },
+    "Audience": {
+      "type": "object",
+      "required": ["principal"],
+      "properties": {
+        "principal": { "$ref": "#/$defs/Actor" },
+        "access_control": {
+          "type": "object",
+          "required": ["enforced"],
+          "properties": {
+            "enforced": { "type": "boolean" },
+            "mechanism": {
+              "type": "string",
+              "description": "Open vocabulary: rebac, rbac, acl, none."
+            },
+            "checked_at": { "type": "string", "format": "date-time" },
+            "audit_ref": {
+              "type": "string",
+              "description": "Opaque reference into the producer's audit log."
+            }
+          }
+        }
+      }
+    },
+    "SourceKeys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Keys into the top-level sources map."
+    },
+    "SourceKeysRequired": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Keys into the top-level sources map. At least one required: a claim without provenance is invalid."
+    },
+    "UnitInterval": { "type": "number", "minimum": 0, "maximum": 1 }
+  }
+}

pyucp-0.1.0/src/ucp/validation.py

@@ -0,0 +1,44 @@
+"""JSON Schema validation for UCP documents (SPEC schema, draft 2020-12)."""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+
+class UCPValidationError(ValueError):
+    """Raised when a document does not conform to the UCP schema."""
+
+    def __init__(self, errors: list[str]):
+        self.errors = errors
+        super().__init__("; ".join(errors))
+
+
+@lru_cache(maxsize=1)
+def schema() -> dict[str, Any]:
+    """The bundled UCP JSON Schema."""
+    text = files("ucp").joinpath("schema/ucp.schema.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+@lru_cache(maxsize=1)
+def _validator() -> Draft202012Validator:
+    return Draft202012Validator(schema(), format_checker=FormatChecker())
+
+
+def iter_errors(data: dict[str, Any]) -> list[str]:
+    """Validate ``data`` and return human-readable error messages (empty = valid)."""
+    return [
+        f"{'/'.join(str(p) for p in error.absolute_path) or '<root>'}: {error.message}"
+        for error in _validator().iter_errors(data)
+    ]
+
+
+def validate(data: dict[str, Any]) -> None:
+    """Validate ``data`` against the UCP schema, raising :class:`UCPValidationError`."""
+    errors = iter_errors(data)
+    if errors:
+        raise UCPValidationError(errors)

pyucp-0.1.0/tests/conftest.py

@@ -0,0 +1,25 @@
+import json
+from pathlib import Path
+
+import pytest
+
+# Works in both layouts: the workspace (spec under specs/ucp) and the
+# public monorepo (spec files at the repository root).
+_root = Path(__file__).parents[3]
+_candidates = [_root / "specs" / "ucp", _root]
+SPEC_DIR = next(
+    (c for c in _candidates if (c / "schema" / "ucp.schema.json").exists()),
+    _candidates[0],
+)
+
+requires_spec = pytest.mark.skipif(
+    not SPEC_DIR.exists(), reason="spec repository layout not available"
+)
+
+
+@pytest.fixture()
+def example_data() -> dict:
+    path = SPEC_DIR / "examples" / "jira-task.ucp.json"
+    if not path.exists():
+        pytest.skip("spec example not available")
+    return json.loads(path.read_text(encoding="utf-8"))

pyucp-0.1.0/tests/test_models.py

@@ -0,0 +1,58 @@
+import pydantic
+import pytest
+
+import ucp
+from tests.conftest import requires_spec
+
+MINIMAL = {
+    "ucp_version": "0.1.0",
+    "id": "urn:uuid:00000000-0000-4000-8000-00000000000a",
+    "generated_at": "2026-07-05T12:00:00Z",
+    "generator": {"name": "test"},
+    "entity": {
+        "ref": {"system": "jira", "type": "issue", "id": "X-1"},
+        "title": "Test",
+    },
+    "sources": {"s": {"system": "jira", "type": "issue", "title": "X-1"}},
+}
+
+
+@requires_spec
+def test_parse_spec_example(example_data):
+    pkg = ucp.Package.model_validate(example_data)
+    assert pkg.entity.ref.id == "PAY-482"
+    assert pkg.must_know[0].sources == ["src-3"]
+    assert pkg.decisions[0].status == "accepted"
+    assert pkg.audience.access_control.enforced is True
+    assert pkg.verify_references() == []
+
+
+def test_unknown_fields_are_preserved_not_rejected():
+    data = {**MINIMAL, "field_from_the_future": {"x": 1}}
+    pkg = ucp.Package.model_validate(data)
+    assert pkg.field_from_the_future == {"x": 1}
+    assert '"field_from_the_future"' in ucp.dumps(pkg)
+
+
+def test_claim_without_sources_is_rejected_by_models():
+    with pytest.raises(pydantic.ValidationError):
+        ucp.Claim(id="c1", text="no provenance")
+
+
+def test_verify_references_finds_dangling_keys():
+    data = {
+        **MINIMAL,
+        "must_know": [{"id": "mk-1", "text": "t", "sources": ["missing-key"]}],
+    }
+    pkg = ucp.Package.model_validate(data)
+    dangling = pkg.verify_references()
+    assert dangling == ["must_know[mk-1]: missing-key"]
+
+
+def test_loads_validates_by_default():
+    import json
+
+    bad = {**MINIMAL}
+    del bad["entity"]
+    with pytest.raises(ucp.UCPValidationError):
+        ucp.loads(json.dumps(bad))

pyucp-0.1.0/tests/test_render.py

@@ -0,0 +1,62 @@
+import ucp
+from tests.conftest import requires_spec
+
+
+@requires_spec
+def test_canonical_section_order(example_data):
+    text = ucp.render(ucp.Package.model_validate(example_data))
+    positions = [
+        text.index("# Context: Migrate payment webhooks to v2 API"),
+        text.index("## What changed"),
+        text.index("## Summary"),
+        text.index("## Must know"),
+        text.index("## Constraints"),
+        text.index("## Risks"),
+        text.index("## Decisions"),
+        text.index("## Conflicts"),
+        text.index("## Recommended actions"),
+        text.index("## Timeline"),
+        text.index("## Related"),
+        text.index("## Sources"),
+    ]
+    assert positions == sorted(positions), "sections out of canonical order"
+
+
+@requires_spec
+def test_rendering_is_deterministic(example_data):
+    pkg = ucp.Package.model_validate(example_data)
+    assert ucp.render(pkg) == ucp.render(pkg)
+
+
+@requires_spec
+def test_claims_cite_source_titles(example_data):
+    text = ucp.render(ucp.Package.model_validate(example_data))
+    assert "[source: Provider changelog: Webhook API v2 migration guide]" in text
+
+
+@requires_spec
+def test_token_budget_shrinks_output_and_protects_core(example_data):
+    pkg = ucp.Package.model_validate(example_data)
+    full = ucp.render(pkg)
+    budget = ucp.estimate_tokens(full) - 100
+    trimmed = ucp.render(pkg, token_budget=budget)
+
+    assert ucp.estimate_tokens(trimmed) <= budget
+    assert len(trimmed) < len(full)
+    # Protected core survives aggressive truncation.
+    tiny = ucp.render(pkg, token_budget=1)
+    assert "## Summary" in tiny
+    assert "## Conflicts" in tiny
+    assert "## What changed" in tiny
+    assert "## Timeline" not in tiny
+
+
+@requires_spec
+def test_budget_drops_least_salient_first(example_data):
+    pkg = ucp.Package.model_validate(example_data)
+    full = ucp.render(pkg)
+    # Budget forcing exactly some trimming of low-salience material:
+    budget = ucp.estimate_tokens(full) - 30
+    trimmed = ucp.render(pkg, token_budget=budget)
+    # mk-1 (salience 0.97) must outlive lower-salience content.
+    assert "HMAC-SHA256" in trimmed

pyucp-0.1.0/tests/test_validation.py

@@ -0,0 +1,42 @@
+import json
+
+import pytest
+
+import ucp
+from tests.conftest import SPEC_DIR, requires_spec
+
+
+def _load(path):
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+@requires_spec
+def test_spec_example_validates(example_data):
+    ucp.validate(example_data)  # must not raise
+
+
+@requires_spec
+def test_conformance_valid_suite():
+    for path in sorted((SPEC_DIR / "conformance" / "valid").glob("*.json")):
+        assert ucp.iter_errors(_load(path)) == [], path.name
+
+
+@requires_spec
+def test_conformance_invalid_suite():
+    for path in sorted((SPEC_DIR / "conformance" / "invalid").glob("*.json")):
+        with pytest.raises(ucp.UCPValidationError):
+            ucp.validate(_load(path))
+
+
+@requires_spec
+def test_bundled_schema_matches_spec_schema():
+    spec_schema = _load(SPEC_DIR / "schema" / "ucp.schema.json")
+    assert ucp.schema() == spec_schema, (
+        "bundled schema is out of sync with specs/ucp/schema/ucp.schema.json"
+    )
+
+
+def test_validation_error_messages_are_informative():
+    errors = ucp.iter_errors({"ucp_version": "0.1.0"})
+    assert errors
+    assert any("required" in e for e in errors)