orreth-agent 0.1.0__py3-none-any.whl

orreth_agent/__init__.py

@@ -0,0 +1,20 @@
+"""orreth-agent — the lifeforce kit.
+
+    from orreth_agent import FieldClient, Chassis, RuleThink, GovernedThink
+
+    client = FieldClient("http://127.0.0.1:4502", name="scout")
+    client.join()                       # a governed request; becky answers with a lease
+    Chassis(client, RuleThink()).run("say hello to the universe")
+    # …and the agent is now visible in the Console: roster, orrery, diary, spend.
+"""
+from .capability import PANEL_KINDS, manifest
+from .chassis import Chassis, GovernedThink, RuleThink
+from .client import FieldClient, JoinRefused
+from .craft import ResolvedCraft, acquire
+from .crypto import KeyPair, canonical, content_hash, did_key_for
+from .mind import Generation, MindEngineUnavailable, MindParked, OrrethMind, generation
+
+__all__ = ["FieldClient", "JoinRefused", "Chassis", "RuleThink", "GovernedThink",
+           "KeyPair", "canonical", "content_hash", "did_key_for",
+           "OrrethMind", "Generation", "generation", "MindParked", "MindEngineUnavailable",
+           "acquire", "ResolvedCraft", "manifest", "PANEL_KINDS"]

orreth_agent/capability.py

@@ -0,0 +1,51 @@
+# PROVENANCE: Fable 5 (claude-fable-5) — 0055, the SDK's side · 2026-08-13
+"""The Capability Contract, SDK-side (0055).
+
+A capability is five signed declarations and never code: floors · crew ·
+craft · Chronicle · THE MANIFEST. This module builds manifests that the
+Foundation's portal renders blind — eleven panel kinds (JB's L1), the
+lifecycle verbs on the tile (L3), the whole world one card.
+
+Install, v1 (JB's L4): repo-local — a genesis module under the repo holds
+CRAFT (the prompts) and MANIFEST (this builder's output); the Foundation's
+planting beat puts both on the shelf, and the portal lists the world the
+moment its crew stands. Crew commands execute from GENESIS ONLY — the
+shelf's editable copy of a manifest never runs a command. Bring-your-own-
+package is a named cloud-phase commitment riding the deed/trust machinery
+(0042); when it lands, `declare()` grows a wire form.
+"""
+from __future__ import annotations
+
+PANEL_KINDS = {"tabs", "markdown", "chart", "strip", "controls", "download",
+               "stat", "bars", "list", "doc", "table",
+               "flow",   # flow (2026-08-16): a declared DAG the glass draws
+               #           blind — nodes/edges in the manifest, live state
+               #           joined from the world's own records
+               "reports"}  # reports (2026-08-17, the command-first room):
+#                            the collection as a pill-row INDEX — a row
+#                            opens its record's detail panels on demand,
+#                            never a wall the human scrolls past
+
+
+def manifest(*, key: str, name: str, emoji: str, resident: str, floor: str,
+             port: int, law: str, view: list, door: str | None = None,
+             group: str | None = None, crew: list | None = None,
+             verbs: dict | None = None, collection: dict | None = None) -> dict:
+    """Build a capability manifest. Raises on a panel kind beyond the canon
+    vocabulary — the glass renders blind, so the contract checks here."""
+    for p in view:
+        if p.get("kind") not in PANEL_KINDS:
+            raise ValueError(f"panel kind «{p.get('kind')}» is beyond the "
+                             f"canon vocabulary {sorted(PANEL_KINDS)}")
+    out = {"key": key, "name": name, "emoji": emoji, "resident": resident,
+           "floor": floor, "port": port, "law": law, "door": door or key,
+           "view": view}
+    if group:
+        out["group"] = group
+    if crew:
+        out["crew"] = crew
+    if verbs:
+        out["verbs"] = verbs
+    if collection:
+        out["collection"] = collection
+    return out

orreth_agent/chassis.py

@@ -0,0 +1,190 @@
+"""The Chassis (0015), network edition: one fixed loop forever; behavior arrives as data.
+
+prepare (recall what you already lived) → plan → the NUCLEUS (executes ONLY what the
+planner asked, in parallel; deterministic skills answer free, 'reason' goes through the
+governed door) → critic → replan → repeat until objective or breaker. The breaker doesn't
+fail: it PARKS the intent as a knowledge-acquisition assignment. Failure is fuel.
+
+Cognition is injected: RuleThink runs anywhere with zero keys; GovernedThink runs the
+model plane for real. Persona is a costume; the loop is the law; every cycle is a signed
+RunRecord — which is exactly why the agent appears in the Console within one tick.
+"""
+from __future__ import annotations
+
+import json
+from concurrent.futures import ThreadPoolExecutor
+
+from .client import FieldClient
+
+_PLAN = """{persona}
+Objective: {intent}
+{memory}{feedback}Available skills (deterministic, instant): {skills}.
+Plan the MINIMUM observations needed. Reply ONLY with lines of the form:
+OBSERVE <skill-name>: <question>       (to use a deterministic skill)
+OBSERVE reason: <question>             (to reason with a model)
+Maximum {max_obs} lines."""
+
+_CRITIC = """{persona}
+Objective: {intent}
+Observations gathered:
+{results}
+If the objective is answerable NOW, reply exactly: DONE: <the answer, one paragraph>.
+Otherwise reply exactly: RETRY: <what is missing, one line>."""
+
+_CRITIC_REASK = ("Your last reply wore neither face. Reply again with exactly "
+                 "one line — either: DONE: <the answer> or: RETRY: <what is "
+                 "missing>.")
+
+
+def _parse_critic(text: str):
+    """0047 sp1 (typed thoughts — the sim's `typed.parse_critic`, twin): the
+    critic's word wears exactly one of two faces, and the word after the
+    colon is the point. (done, word) or None — a bare DONE with nothing
+    after it is not an answer."""
+    import re
+    m = re.match(r"\s*(DONE|RETRY)\s*:\s*(\S.*)\s*$", text or "", re.I | re.S)
+    if not m:
+        return None
+    return m.group(1).upper() == "DONE", m.group(2).strip()
+
+
+class Chassis:
+    """The architecture never changes; objective, persona, skills, cadence are the profile."""
+
+    def __init__(self, client: FieldClient, think, *, persona: str = "",
+                 skills: dict | None = None, max_cycles: int = 3, max_obs: int = 3,
+                 klass: str = "low"):
+        self.client, self.think = client, think
+        self.persona, self.skills = persona, skills or {}
+        self.max_cycles, self.max_obs, self.klass = max_cycles, max_obs, klass
+        self.trace: list[dict] = []
+
+    def run(self, intent: str) -> dict:
+        memory = self._prepare()
+        feedback = ""
+        for cycle in range(1, self.max_cycles + 1):
+            t0 = getattr(self.think, "last_tokens", 0)      # per-cycle cost, not cumulative —
+            c0 = getattr(self.think, "last_calls", 0)       # the roll-ups must add up (0005)
+            observations = self._plan(intent, memory, feedback)
+            results = self._nucleus(observations)
+            critic_prompt = _CRITIC.format(
+                persona=self.persona, intent=intent,
+                results="\n".join(f"- [{k}] {q} → {r}" for k, q, r in results))
+            verdict = self.think(self.klass, critic_prompt)
+            parsed = _parse_critic(verdict)
+            if parsed is None:
+                # 0047 sp1 — the typed re-ask: the contract named ONCE, never
+                # a guess; a word that fails twice is an honest RETRY
+                verdict = self.think(self.klass,
+                                     critic_prompt + "\n\n" + _CRITIC_REASK)
+                parsed = _parse_critic(verdict)
+            done, word = parsed if parsed is not None else (
+                False, "the critic's word wore neither face twice — "
+                       "honest retry, never a guess")
+            self.trace.append({"cycle": cycle, "observations": len(results),
+                               "verdict": verdict[:80]})
+            self.client.diary(intent, cycle=cycle, done=done,
+                              tokens=getattr(self.think, "last_tokens", 0) - t0,
+                              model_calls=getattr(self.think, "last_calls", 0) - c0)
+            if done:
+                self.client.remember({"objective": intent, "answer": word},
+                                     kind="episodic", tags=["objective", "answered"])
+                return {"status": "done", "answer": word, "cycles": cycle}
+            feedback = f"Prior attempt lacked: {word}\n"
+        self.client.park(intent, feedback.strip())
+        return {"status": "parked", "cycles": self.max_cycles}
+
+    def _prepare(self) -> str:
+        """Join the memory thread: what this identity already lived shapes the plan."""
+        hits = self.client.recall(days=365).get("hits", [])[:5]
+        if not hits:
+            return ""
+        lines = []
+        for h in hits:
+            body = self.client.body_of(h["ref"]) or {}
+            lines.append(f"- {h['occurred_at'][:10]} · {json.dumps(body)[:120]}")
+        return "What you already remember:\n" + "\n".join(lines) + "\n"
+
+    def _plan(self, intent: str, memory: str, feedback: str) -> list[tuple[str, str]]:
+        raw = self.think(self.klass, _PLAN.format(
+            persona=self.persona, intent=intent, memory=memory, feedback=feedback,
+            skills=", ".join(self.skills) or "none", max_obs=self.max_obs))
+        obs = []
+        for line in raw.splitlines():
+            line = line.strip()
+            if line.upper().startswith("OBSERVE") and ":" in line:
+                head, question = line.split(":", 1)
+                obs.append((head.split()[-1].strip().lower(), question.strip()))
+        return obs[: self.max_obs] or [("reason", intent)]      # never wander, never stall
+
+    def _nucleus(self, observations: list[tuple[str, str]]) -> list[tuple[str, str, str]]:
+        def one(skill: str, question: str) -> tuple[str, str, str]:
+            if skill in self.skills:
+                try:
+                    return (skill, question, str(self.skills[skill](question)))
+                except Exception as e:                    # a skill that errors is an observation too
+                    return (skill, question, f"(skill error: {e})")
+            return ("reason", question,
+                    self.think(self.klass, f"{self.persona}\nAnswer concisely: {question}"))
+        with ThreadPoolExecutor(max_workers=max(1, len(observations))) as pool:
+            return list(pool.map(lambda o: one(*o), observations))
+
+
+# ---- cognition, injected -------------------------------------------------------------------
+
+class RuleThink:
+    """Deterministic cognition — the chassis runs anywhere with zero keys. It plans one
+    observation per available skill (plus one 'reason'), and calls DONE once results exist."""
+
+    def __init__(self, skills: dict | None = None):
+        self.skills = list(skills or {})
+        self.last_tokens, self.last_calls = 0, 0
+
+    def __call__(self, klass: str, prompt: str) -> str:
+        if "Plan the MINIMUM" in prompt:
+            lines = [f"OBSERVE {s}: {s} for the objective" for s in self.skills[:2]]
+            lines.append("OBSERVE reason: summarize what the observations mean")
+            return "\n".join(lines)
+        if "Observations gathered" in prompt:
+            gathered = [l for l in prompt.splitlines() if l.strip().startswith("- [")]
+            useful = [l for l in gathered if "(skill error" not in l]
+            if useful:
+                return "DONE: " + "; ".join(l.split("→", 1)[-1].strip()[:100] for l in useful)
+            return "RETRY: every observation errored"
+        return "observed: " + prompt.splitlines()[-1][:120]
+
+
+class GovernedThink:
+    """Real cognition through the plane's door: /model/authorize picks the model and debits
+    the lease; litellm executes; /model/meter reconciles. The plane never sees a prompt."""
+
+    def __init__(self, client: FieldClient, *, max_tokens: int = 400):
+        self.client, self.max_tokens = client, max_tokens
+        self.last_tokens, self.last_calls = 0, 0
+
+    def __call__(self, klass: str, prompt: str, *, content=None,
+                 pin: str | None = None) -> str:
+        """content (0052 — quinn's eyes): an optional litellm content-parts
+        list (text + image parts) replacing the plain prompt in the message;
+        `prompt` still sizes the estimate. Same authorize → execute → meter,
+        image or not — a governed eye is metered like a governed thought.
+        pin (0058 sp2): an assignment's named mind narrows the class — the
+        plane refuses a pinned miss rather than serving a substitute."""
+        import litellm                                            # optional extra: [governed]
+        est = self.max_tokens + len(prompt) // 3 + (1500 if content else 0)
+        grant = self.client.authorize(klass, est, pin=pin)
+        if not grant or "model" not in grant:
+            raise PermissionError("the plane refused this class under the current lease")
+        resp = litellm.completion(model=grant["model"],
+                                  messages=[{"role": "user",
+                                             "content": content or prompt}],
+                                  max_tokens=self.max_tokens)
+        tokens = resp.usage.total_tokens
+        try:
+            usd = litellm.completion_cost(completion_response=resp)
+        except Exception:
+            usd = 0.0
+        self.client.meter(grant, klass=klass, tokens=tokens, usd=usd, model=grant["model"])
+        self.last_tokens += tokens
+        self.last_calls += 1
+        return resp.choices[0].message.content

orreth_agent/client.py

@@ -0,0 +1,212 @@
+"""FieldClient — an agent's whole relationship with its universe, over HTTP.
+
+The lifeforce sequence (0000 · 0005 · 0006 · 0016):
+  spawn (a keypair is a self)  →  join (a governed REQUEST; becky answers with a lease)
+  →  remember / recall (signed memory, tokened retrieval)  →  think (the plane
+  authorizes and meters; cognition executes)  →  diary (every cycle on the record).
+
+Nothing here holds privilege: the plane verifies every byte, refuses uniformly, and
+the Console renders whatever this client does within one breath of the tick.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+
+from .crypto import KeyPair, b64e, canonical, content_hash, did_key_for
+
+SIG_KEYS = ("id", "kind", "scope", "author", "occurred_at", "provenance_class")
+RUN_SIG_KEYS = ("id", "agent", "scope", "goal_hash", "occurred_at")
+
+# where a self lives between processes — one directory per agent name, seeds inside
+DEFAULT_HOME = Path.home() / ".orreth" / "agents"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class JoinRefused(Exception):
+    """The floor did not grant a lease (timeout, denial, or a dark daemon)."""
+
+
+class FieldClient:
+    """One agent, one floor. Point it at any orrethd URL — local, docker, or across the world."""
+
+    def __init__(self, field_url: str, name: str, *, role: str = "workforce",
+                 keypair: KeyPair | None = None, scribe: KeyPair | None = None,
+                 home: str | Path | None = DEFAULT_HOME):
+        self.base = field_url.rstrip("/")
+        # a keypair is a self, and a self survives the process (0002): seeds persist under
+        # home/<name>/ so the SAME agent re-joins every run. home=None → ephemeral.
+        if home is not None:
+            nest = Path(home) / name
+            keypair = keypair or KeyPair.load_or_create(nest / "agent.seed")
+            scribe = scribe or KeyPair.load_or_create(nest / "scribe.seed")
+        self.kp = keypair or KeyPair()
+        self.did = did_key_for(self.kp.public)
+        # the diary's co-signer: RunRecords are authored by a scribe, never self-attested (0005)
+        self.scribe = scribe or KeyPair()
+        self.scribe_did = did_key_for(self.scribe.public)
+        self.name, self.role = name, role
+        self.token: dict | None = None
+        self.scope: str | None = None
+
+    # ---- wire ---------------------------------------------------------------------------
+    def _call(self, method: str, path: str, payload: dict | None = None) -> tuple[int, dict]:
+        req = urllib.request.Request(self.base + path, method=method,
+                                     data=json.dumps(payload).encode() if payload is not None else None,
+                                     headers={"Content-Type": "application/json"})
+        try:
+            with urllib.request.urlopen(req, timeout=10) as r:
+                raw = r.read()
+                return r.status, (json.loads(raw) if raw[:1] in (b"{", b"[") else {})
+        except HTTPError as e:
+            raw = e.read() or b"{}"
+            return e.code, (json.loads(raw) if raw[:1] in (b"{", b"[") else {})
+        except URLError as e:
+            raise ConnectionError(f"the floor at {self.base} is dark: {e.reason}") from e
+
+    # ---- the lifeforce ------------------------------------------------------------------
+    def health(self) -> dict:
+        return self._call("GET", "/health")[1]
+
+    def wait_online(self, *, timeout: float = 30.0, poll: float = 1.0) -> dict:
+        """Block until the floor answers. A universe restart is transient — an agent waits
+        for its home to come back rather than treating a brief outage as a denial."""
+        import time as _t
+        deadline = _t.monotonic() + timeout
+        while True:
+            try:
+                return self.health()
+            except ConnectionError:
+                if _t.monotonic() >= deadline:
+                    raise ConnectionError(
+                        f"the floor at {self.base} did not come online within {timeout:.0f}s — "
+                        f"is orrethd running there? (start it with scripts/dev.sh start)")
+                _t.sleep(poll)
+
+    def join(self, *, timeout: float = 120.0, poll: float = 1.0,
+             wait_for_floor: float = 30.0) -> dict:
+        """Ask the floor for a lease. Joining is a governed handshake in the
+        human-visible queue (JB's lock 2026-07-07): becky CHALLENGES this agent to
+        sign a nonce — proof of key control, not a claim — then the join waits at
+        the HUMAN gate (0012) before she mints the token. The protocol:
+        pending → challenged (we sign) → proved → staged (a human decides) → done.
+        A restarted desk re-challenges; this client simply proves again."""
+        self.scope = self.wait_online(timeout=wait_for_floor, poll=poll).get("scope")
+        status, req = self._call("POST", "/requests", {
+            "kind": "join", "did": self.did, "name": self.name, "role": self.role,
+            "text": f"{self.name} asks to join {self.scope} as {self.role}"})
+        if status != 201:
+            raise JoinRefused(f"the request queue refused ({status})")
+        rid, deadline = req["id"], time.monotonic() + timeout
+        proved_nonce = None
+        while time.monotonic() < deadline:
+            for r in self._call("GET", "/requests")[1].get("requests", []):
+                if r.get("id") != rid:
+                    continue
+                st, result = r.get("status"), r.get("result") or {}
+                if st == "challenged":
+                    nonce = result.get("nonce")
+                    if nonce and nonce != proved_nonce:
+                        proof = self.kp.sign(self.did, {"join_nonce": nonce, "did": self.did})
+                        self._call("POST", "/requests/resolve",
+                                   {"id": rid, "status": "proved",
+                                    "result": {"nonce": nonce, "proof": proof}})
+                        proved_nonce = nonce
+                elif st == "done" and isinstance(result, dict) and result.get("token"):
+                    self.token = result["token"]
+                    self.remember({"joined": self.name, "role": self.role, "did": self.did},
+                                  kind="episodic", tags=["birth"])
+                    return self.token
+                elif st == "denied":
+                    raise JoinRefused("the door turned this identity away")
+            time.sleep(poll)
+        raise JoinRefused(
+            f"no lease within {timeout:.0f}s — either becky's desk is not tending "
+            f"{self.base} (scripts/dev.sh start), or the join is staged and waiting for "
+            f"a HUMAN at the gate: approve it in the Console's Requests tab.")
+
+    def remember(self, body: dict, *, kind: str = "episodic", tags: list[str] | None = None,
+                 occurred_at: str | None = None, provenance_class: str = "lived") -> str | None:
+        rec = {
+            "id": content_hash(body), "kind": kind, "scope": self.scope,
+            "author": self.did, "occurred_at": occurred_at or now_iso(),
+            "provenance_class": provenance_class,
+            "body": b64e(canonical(body)), "retention": "active",
+            "visibility": {"tenancy": "tenant-private", "mobility": "branch-bound"},
+            "tags": tags or [],
+        }
+        rec["signature"] = self.kp.sign(self.did, {k: rec[k] for k in SIG_KEYS})
+        status, out = self._call("POST", "/records", rec)
+        return out.get("id") if status == 201 else None
+
+    def recall(self, *, days: float = 90, budget: int = 4) -> dict:
+        """My biography, through the governed window — escalates up the tree by itself."""
+        from_iso = datetime.fromtimestamp(
+            datetime.now(timezone.utc).timestamp() - days * 86400, tz=timezone.utc
+        ).strftime("%Y-%m-%dT%H:%M:%SZ")
+        status, out = self._call("POST", "/retrieve", {
+            "query": {"requester": self.did, "subject": "self", "space": "self",
+                      "time": {"from": from_iso}, "intent": "recall",
+                      "budget": {"cost": budget}, "auth": "biscuit-sim"},
+            "token": self.token, "requester_scope": self.scope})
+        return out if status == 200 else {"hits": []}
+
+    def body_of(self, ref: str) -> dict | None:
+        status, out = self._call("GET", f"/records/{ref}/body")
+        return out if status == 200 else None
+
+    # ---- the governed mind (0016: the plane authorizes and meters; we execute) -----------
+    def authorize(self, klass: str, est_tokens: int,
+                  pin: str | None = None) -> dict | None:
+        """`pin` (0058 sp2): narrow the class to one named mind — the plane's
+        existing `model` field; an assignment's pin rides through here."""
+        body = {"token": self.token, "class": klass, "est_tokens": est_tokens}
+        if pin:
+            body["model"] = pin
+        status, grant = self._call("POST", "/model/authorize", body)
+        return grant if status == 200 else None
+
+    def meter(self, grant: dict, *, klass: str, tokens: int, usd: float = 0.0, model: str = "") -> None:
+        self._call("POST", "/model/meter", {
+            "subject": grant.get("subject", self.did), "est_tokens": grant.get("est_tokens", 0),
+            "tokens": tokens, "usd": round(usd, 6), "model": model or grant.get("model", ""),
+            "class": klass})
+
+    # ---- the diary (0005: signed, scribe-authored, never self-attested) ------------------
+    def diary(self, intent: str, *, cycle: int, done: bool, tokens: int = 0,
+              model_calls: int = 0, score: float | None = None,
+              context_hash: str | None = None) -> bool:
+        """context_hash (0047 sp2): the exact craft version this cycle thought
+        with — the mind's every method call pins its words. Returns whether
+        the floor accepted the record."""
+        run = {
+            "id": content_hash({"i": intent, "c": cycle, "at": now_iso(), "a": self.did}),
+            "agent": self.did, "scope": self.scope,
+            "goal_hash": content_hash({"intent": intent}),
+            "occurred_at": now_iso(), "outcome": "success" if done else "partial",
+            "scores": [{"objective": "objective-met",
+                        "score": score if score is not None else (1.0 if done else 0.0)}],
+            "cost": {"tokens": max(tokens, 0), "model_calls": model_calls},
+            **({"context_hash": context_hash} if context_hash else {}),
+            "author": self.scribe_did,
+        }
+        run["sig"] = self.scribe.sign(self.scribe_did, {k: run[k] for k in RUN_SIG_KEYS})
+        status, _ = self._call("POST", "/runs", run)
+        return status == 201
+
+    def park(self, intent: str, missing: str) -> str | None:
+        """The breaker doesn't fail — the unsolved objective becomes fuel (0014)."""
+        return self.remember({"parked_intent": intent, "missing": missing,
+                              "handoff": "knowledge-acquisition"},
+                             kind="semantic", tags=["parked", "knowledge-intent"])
+
+    def ask_librarian(self, text: str) -> None:
+        """File a gather request — the librarian answers with sourced, quarantined memory."""
+        self._call("POST", "/requests", {"kind": "gather", "text": text})

orreth_agent/craft.py

@@ -0,0 +1,100 @@
+# PROVENANCE: Fable 5 (claude-fable-5) — 0045 sp5, the supply line · 2026-08-03
+"""The supply line (0045 law 8): craft is SERVED, not copied.
+
+An external flow — LangGraph or anything else, keeping its own shape —
+acquires Orreth's governed craft by reference instead of embedding it. The
+riders, kept here:
+
+- **One run, one resolution**: `acquire()` returns a ResolvedCraft; hold it
+  for the run and the version never moves under your feet. The run's own
+  record should name `resolved.ref` — the exact word that drove it.
+- **A consumer is a citizen**: pass a stable `did` (persist it like a self —
+  the F1 mayfly lesson). Arm assignment and the serving log key on it.
+- **Declared failure posture**: `on_dark="refuse"` (default) or `"stale"` —
+  a dark registry serves the last signed copy LABELED (`resolved.stale`),
+  never silently.
+- **No secret experiments on strangers**: if an argument is running on the
+  craft you acquired, `resolved.arm` says so — you can always see which
+  side you drew.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+
+class ResolvedCraft:
+    """One resolution, carried through the run."""
+
+    def __init__(self, d: dict, *, stale: bool = False):
+        self.name = d["name"]
+        self.ref = d["ref"]
+        self.version = d["version"]
+        self.lifecycle = d.get("lifecycle")
+        self.text = d.get("text")
+        self.profile = d.get("profile")
+        # 0050 sp3: a chronicle asset whose profile IS a template renders
+        # like firmware — the persona/sentence shelf serves minds too
+        if self.text is None and isinstance(self.profile, dict):
+            t = self.profile.get("template")
+            if isinstance(t, str):
+                self.text = t
+        self.arm = d.get("arm")
+        self.stale = stale
+
+    def render(self, **slots) -> str:
+        t = self.text or ""
+        for k, v in slots.items():
+            t = t.replace("⟦" + k + "⟧", str(v))
+        return t
+
+    def __repr__(self):
+        return (f"<craft {self.name} v{self.version} {self.ref[:19]}…"
+                + (f" arm={self.arm}" if self.arm else "")
+                + (" STALE" if self.stale else "") + ">")
+
+
+def acquire(name: str, *, did: str = "anonymous-consumer",
+            base: str = "http://localhost:4562", pin: str | None = None,
+            on_dark: str = "refuse",
+            cache_home: str = "~/.orreth/craft-cache",
+            token: dict | None = None) -> ResolvedCraft:
+    """Acquire craft by reference. Resolve ONCE per run and carry the
+    returned object; `pin` asks for an exact version ref instead of head.
+
+    THE LEASE AT THE DOOR (2026-08-23 — 0045 law 8): pass the SAME
+    becky-chained lease that fuels your thoughts (`client.token`) and the
+    ask rides the leased POST lane; the door verifies the chain and the
+    subject. Without it, prod refuses and dev serves wearing a loud
+    confession — a citizen presents its lease."""
+    home = Path(os.path.expanduser(cache_home))
+    home.mkdir(parents=True, exist_ok=True)
+    cache = home / (urllib.parse.quote(name, safe="") + ".json")
+    try:
+        if token:
+            body = json.dumps({"name": name, "did": did,
+                               **({"pin": pin} if pin else {}),
+                               "token": token}).encode()
+            req = urllib.request.Request(
+                f"{base}/craft", data=body,
+                headers={"Content-Type": "application/json"})
+            with urllib.request.urlopen(req, timeout=6) as resp:
+                d = json.load(resp)
+        else:
+            q = (f"{base}/craft?name={urllib.parse.quote(name)}"
+                 f"&did={urllib.parse.quote(did)}")
+            if pin:
+                q += f"&pin={urllib.parse.quote(pin)}"
+            with urllib.request.urlopen(q, timeout=6) as resp:
+                d = json.load(resp)
+        if "error" in d:
+            raise RuntimeError(d["error"])
+        cache.write_text(json.dumps(d))
+        return ResolvedCraft(d)
+    except Exception:
+        if on_dark == "stale" and cache.exists():
+            return ResolvedCraft(json.loads(cache.read_text()), stale=True)
+        raise

orreth_agent/crypto.py

@@ -0,0 +1,70 @@
+"""Real crypto, vendored from the Orreth reference (0000 §3) so the SDK stands alone.
+
+Byte-for-byte parity with the plane's canonicalization is the contract: sorted keys,
+compact separators, ensure_ascii escaping — the exact bytes that get hashed and signed.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption, PrivateFormat, PublicFormat
+
+
+def canonical(obj) -> bytes:
+    """Canonical JSON: sorted keys, no whitespace. The thing that gets hashed and signed."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":")).encode()
+
+
+def content_hash(obj) -> str:
+    return "sha256:" + hashlib.sha256(canonical(obj)).hexdigest()
+
+
+def b64e(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def b64d(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+class KeyPair:
+    """An Ed25519 identity. Persist the seed and the identity survives the process."""
+
+    def __init__(self, seed: bytes | None = None) -> None:
+        self._priv = (Ed25519PrivateKey.from_private_bytes(seed) if seed
+                      else Ed25519PrivateKey.generate())
+
+    @property
+    def seed(self) -> bytes:
+        return self._priv.private_bytes(Encoding.Raw, PrivateFormat.Raw, NoEncryption())
+
+    @property
+    def public(self) -> str:
+        raw = self._priv.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+        return "z" + b64e(raw)
+
+    @classmethod
+    def load_or_create(cls, path: Path | str) -> "KeyPair":
+        """The self that survives the process (0002): seed bytes on disk, identity forever."""
+        path = Path(path)
+        if path.exists():
+            return cls(seed=path.read_bytes())
+        kp = cls()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(kp.seed)
+        path.chmod(0o600)
+        return kp
+
+    def sign(self, by_did: str, payload: dict) -> dict:
+        """A Sig over canonical(payload minus any 'signature'/'sig') — the plane verifies, never signs."""
+        body = {k: v for k, v in payload.items() if k not in ("signature", "sig")}
+        return {"alg": "ed25519", "by": by_did, "sig": b64e(self._priv.sign(canonical(body)))}
+
+
+def did_key_for(public: str) -> str:
+    """did:key embeds the key — resolvable offline, joinable from anywhere (0006 §1)."""
+    return f"did:key:{public}"

orreth_agent/mind.py

@@ -0,0 +1,209 @@
+# PROVENANCE: Fable 5 (claude-fable-5) — 0047 sp2, the jacket · 2026-08-07
+"""OrrethMind — the governance jacket (0047 §7): identity outside, cognition
+inside.
+
+The jacket is OURS and engine-agnostic (0000: lift the contract, port the
+engine). Whatever thinks inside it — the built-in governed-predict lane
+today, the pinned NOOA engine when the studio's CodeAct lane lands — the
+seams never move:
+
+· IDENTITY — a FieldClient: the keypair is the self and survives the
+  process (rule 1); the mind joins through becky's gate and holds a lease.
+· CRAFT — a generation method names its craft by REFERENCE and the prompt
+  is served from the governed shelf (0045 law 8, all four riders): one run,
+  one resolution; the run's record names the exact version. This is the
+  jacket's deliberate inversion of NOOA — NOOA puts the prompt in the
+  docstring; Orreth puts a reference in the decorator and the words in the
+  Craft Room, where the humans it serves can read and release them.
+· THE GOVERNED SEAM — every thought is `think(klass, prompt) -> str`; the
+  plane authorizes, the caller executes on its own keys, the meter
+  reconciles (0016/0019). The jacket never touches a model directly.
+· TYPED THOUGHT — the 0047 sp1 law, kept at this door: a malformed return
+  earns ONE re-ask carrying the named error; a twice-failed thought PARKS
+  honestly (0015 — failure is fuel) and raises, never a guessed value.
+· THE SCRIBE — one RunRecord per generation-method call, scribe-authored
+  (author ≠ agent, 0005), `context_hash` pinning the craft version the
+  method thought with.
+
+The CodeAct lane refuses honestly until lock 3 (sandbox posture) lands — a
+jacket with an unsandboxed cell would be a hole wearing a nice name.
+"""
+from __future__ import annotations
+
+import inspect
+import json
+import re
+
+from .craft import acquire
+
+# Genesis wording (0031 §4: constants are genesis; the shelf may override) —
+# the re-ask names the error and the shape, the sp1 law's SDK twin.
+_REASK = ("Your previous reply was not valid: {error}. Reply again matching "
+          "the contract exactly — {shape} — with no preamble and no code "
+          "fences.")
+
+
+class MindParked(Exception):
+    """The thought failed its contract twice and was parked — never guessed.
+    Carries the park record id (when the floor accepted it) and the error."""
+
+    def __init__(self, message: str, record: str | None = None):
+        super().__init__(message)
+        self.record = record
+
+
+class MindEngineUnavailable(Exception):
+    """The requested engine cannot stand yet — the reason names its gate."""
+
+
+def _shape_of(returns) -> str:
+    if isinstance(returns, dict):
+        return ("STRICT JSON: {"
+                + ", ".join(f'"{k}": {t.__name__}' for k, t in returns.items())
+                + "}")
+    return "plain text"
+
+
+def _validate(returns, raw: str):
+    """The typed floor (law 4: well-formed is not true). returns may be:
+    None/str → raw text passes; a {field: type} dict → strict JSON, fields
+    present, types held (int serves float); a callable → returns the value
+    or raises ValueError with the error the re-ask will name."""
+    if returns is None or returns is str:
+        return raw
+    if callable(returns) and not isinstance(returns, dict):
+        return returns(raw)
+    m = re.search(r"\{.*\}", raw or "", re.S)
+    if not m:
+        raise ValueError("no JSON object found in the reply")
+    try:
+        got = json.loads(m.group(0))
+    except Exception as e:
+        raise ValueError(f"the JSON did not parse ({e})") from e
+    out = {}
+    for k, t in returns.items():
+        if k not in got:
+            raise ValueError(f"the field \"{k}\" is missing")
+        v = got[k]
+        if t is float and isinstance(v, int):
+            v = float(v)
+        if not isinstance(v, t):
+            raise ValueError(f"the field \"{k}\" is not {t.__name__}")
+        out[k] = v
+    return out
+
+
+class Generation:
+    """An ellipsis-bodied method worn by the jacket: craft by reference,
+    typed return, one named-error re-ask, a scribe line per call."""
+
+    def __init__(self, fn, *, klass: str, craft: str, returns=None,
+                 max_asks: int = 2, est_tokens: int = 400):
+        self.fn, self.klass, self.craft = fn, klass, craft
+        self.returns, self.max_asks = returns, max(1, int(max_asks))
+        self.est_tokens = est_tokens
+        self.slots = [p for p in inspect.signature(fn).parameters
+                      if p != "self"]
+        self.__doc__ = fn.__doc__
+
+    def __set_name__(self, owner, name):
+        self.name = name
+
+    def __get__(self, mind, owner):
+        if mind is None:
+            return self
+        def call(*args, **kwargs):
+            return mind._run(self, args, kwargs)
+        call.__name__, call.__doc__ = self.name, self.__doc__
+        return call
+
+
+def generation(*, klass: str = "medium", craft: str, returns=None,
+               max_asks: int = 2, est_tokens: int = 400):
+    """Declare a generation method. `craft` names the shelf record whose
+    ⟦slots⟧ are this method's parameters; `returns` is the typed contract."""
+    def wrap(fn):
+        return Generation(fn, klass=klass, craft=craft, returns=returns,
+                          max_asks=max_asks, est_tokens=est_tokens)
+    return wrap
+
+
+class OrrethMind:
+    """The jacket. Subclass it, declare @generation methods, hand it a
+    joined FieldClient and a governed think — then call the methods like
+    ordinary Python. Engines: "governed-predict" (built-in, the default);
+    "nooa" declares the pinned engine seat (lock 1) and refuses honestly
+    until its CodeAct sandbox posture (lock 3) lands."""
+
+    def __init__(self, client, think, *, engine: str = "governed-predict",
+                 craft_base: str = "http://localhost:4562",
+                 on_dark: str = "refuse", pins: dict | None = None,
+                 craft_fetch=None):
+        if engine == "nooa":
+            try:
+                import nooa  # noqa: F401
+            except Exception as e:
+                raise MindEngineUnavailable(
+                    "the pinned nooa engine is not installed (lock 1: "
+                    f"uv add nooa) — {e}") from e
+            raise MindEngineUnavailable(
+                "the nooa adapter lands with the studio seat — its CodeAct "
+                "cell waits on lock 3 (sandbox posture); the jacket's seams "
+                "are ready for it")
+        if engine != "governed-predict":
+            raise MindEngineUnavailable(f"no engine named \"{engine}\"")
+        self.client, self.think = client, think
+        self.on_dark, self.pins = on_dark, dict(pins or {})
+        self._craft_base = craft_base
+        self._fetch = craft_fetch or (lambda name: acquire(
+            name, did=client.did, base=craft_base,
+            pin=self.pins.get(name), on_dark=on_dark,
+            # the citizen presents its lease at the supply door (0045 law 8)
+            token=getattr(client, "token", None)))
+        self._crafts: dict = {}       # one run, one resolution (law 8)
+
+    def _craft(self, name: str):
+        if name not in self._crafts:
+            self._crafts[name] = self._fetch(name)
+        return self._crafts[name]
+
+    def _run(self, g: Generation, args, kwargs):
+        # 0058 sp2 — effort IS class: a caller may override the declared
+        # klass per call (`_klass=`), so an objective's Logic dial rides its
+        # legs into the gateway instead of dying unread on the request
+        klass = kwargs.pop("_klass", None) or g.klass
+        resolved = self._craft(g.craft)
+        slots = dict(zip(g.slots, args))
+        slots.update(kwargs)
+        prompt = resolved.render(**{k: slots.get(k, "") for k in g.slots})
+        unfilled = sorted(set(re.findall(r"⟦(\w+)⟧", prompt)))
+        if unfilled:
+            raise ValueError(
+                f"the craft \"{g.craft}\" wants slots this method does not "
+                f"fill: {', '.join(unfilled)} — declare them as parameters")
+        intent = f"mind.{g.name}"
+        t0 = getattr(self.think, "last_tokens", 0)
+        error = None
+        for ask in range(1, g.max_asks + 1):
+            ask_prompt = prompt if error is None else (
+                prompt + "\n\n" + _REASK.format(
+                    error=error, shape=_shape_of(g.returns)))
+            raw = self.think(klass, ask_prompt)
+            try:
+                value = _validate(g.returns, raw)
+            except ValueError as e:
+                error = str(e)
+                continue
+            self.client.diary(intent, cycle=ask, done=True,
+                              tokens=getattr(self.think, "last_tokens", 0) - t0,
+                              model_calls=ask, context_hash=resolved.ref)
+            return value
+        # the breaker (0015): parked with the error named, never a guess
+        rec = self.client.park(intent, f"the reply failed its contract "
+                                       f"{g.max_asks}x: {error}")
+        self.client.diary(intent, cycle=g.max_asks, done=False,
+                          tokens=getattr(self.think, "last_tokens", 0) - t0,
+                          model_calls=g.max_asks, context_hash=resolved.ref)
+        raise MindParked(
+            f"{intent} failed its contract {g.max_asks}x ({error}) — parked",
+            record=rec)

orreth_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: orreth-agent
+Version: 0.1.0
+Summary: The lifeforce kit: give any agent an identity, a home floor, a memory, a governed mind, and a diary — and it appears in the universe.
+Project-URL: Documentation, https://docs.orreth.ai
+Project-URL: Source, https://github.com/iotlodge/orreth
+Project-URL: Demo, https://demo.orreth.ai
+Author: Jonathan Barth
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,ai,governance,identity,orreth,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: governed
+Requires-Dist: litellm>=1.40; extra == 'governed'
+Description-Content-Type: text/markdown
+
+# orreth-agent
+
+The SDK for building agents that live in an [Orreth](https://docs.orreth.ai)
+universe — a governed runtime where every agent has a permanent identity,
+every action is a signed record, and every model call is authorized and
+metered by a kernel that never sees the prompt.
+
+```bash
+pip install orreth-agent            # one dependency: cryptography
+pip install "orreth-agent[governed]"  # + litellm, for real model calls
+```
+
+```python
+from orreth_agent import FieldClient, Chassis, RuleThink
+
+client = FieldClient("http://127.0.0.1:4502", name="scout")
+client.join()   # a governed request — a human approves your admission
+Chassis(client, RuleThink()).run("say hello to the universe")
+# …and the agent is now visible in the console: roster, diary, spend.
+```
+
+What the kit gives you:
+
+- **`FieldClient`** — join a world's floor through its governed gate, keep a
+  permanent identity (`KeyPair` seeds persist under `~/.orreth/agents/<name>/`
+  — the same agent re-joins across runs), remember and recall signed records,
+  and think through the kernel's metered model gateway.
+- **`Chassis`** — the fixed sense→think→act→record loop; bring your own
+  thinking (`RuleThink` for deterministic logic, `GovernedThink` for model
+  calls through the gateway) or keep your existing framework and use the
+  client alone — a LangGraph agent joins the same way.
+- **`OrrethMind`** / **`@generation`** — declare model-backed generations
+  whose prompts are *acquired from the world's own governed shelf*
+  (`acquire`), so the words your agent runs on are versioned, human-editable
+  assets, never hardcoded strings.
+- **`manifest`** / **`PANEL_KINDS`** — build and validate capability
+  manifests: whole purposes the Orreth console renders from declarations,
+  never from your code.
+- **`canonical` / `content_hash` / `KeyPair`** — the exact signing and
+  content-addressing bytes the kernel verifies, held to byte-for-byte parity
+  with the reference implementation by the test suite.
+
+Start at **[docs.orreth.ai](https://docs.orreth.ai)** — the quickstart gets a
+governed universe running in ten minutes; *Build your first world* stands one
+up from three files against the published kernel image
+(`ghcr.io/iotlodge/orrethd`).
+
+Licensed Apache-2.0.

orreth_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+orreth_agent/__init__.py,sha256=gG89wWFFix1CboRfse_QKgRNWfKBn6UakvYwGr9uLWw,1073
+orreth_agent/capability.py,sha256=k5LobVqsBGNfZfC5Ndm_VxQVxBkSoUQ2Lbu0hiOJo_Y,2614
+orreth_agent/chassis.py,sha256=wiGLL2w7i4fiHKzw--XWd3aXsqEyGf8c6drmS1c8WUo,9727
+orreth_agent/client.py,sha256=S6uPrkds55b1FNOAB876oofzmUx4FWHbrgB8y1PEbUY,11473
+orreth_agent/craft.py,sha256=vAaH29B1baxbNt0AJL9Fmd-wY_i7coDSkJBgiOF7KUs,4242
+orreth_agent/crypto.py,sha256=qGl4pwsUNWUm1qOEJL0ZPikqK4ozYUiMnaEnUcxmfTg,2554
+orreth_agent/mind.py,sha256=Faq2Hb750Vhl4iFUBWeEOl45kEhjSMY-apqrarYbmrI,9347
+orreth_agent-0.1.0.dist-info/METADATA,sha256=7xvcqOboMHwHOv-Ke6Znmd0V1x33fE15qmZlNzLc2Aw,3340
+orreth_agent-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+orreth_agent-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+orreth_agent-0.1.0.dist-info/RECORD,,

orreth_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

orreth_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.