metis-memory 0.1.0__tar.gz

metis_memory-0.1.0/LICENSE

@@ -0,0 +1,94 @@
+                                 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.
+
+      "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.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship made available under the
+      License, as indicated by a copyright notice that is included in or
+      attached to the work.
+
+      "Derivative Works" shall mean any work that is based on (or derived
+      from) the Work.
+
+      "Contribution" shall mean any work of authorship submitted to
+      Licensor for inclusion in the Work.
+
+      "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.
+
+   4. Redistribution. You may reproduce and distribute copies of the Work
+      or Derivative Works thereof in any medium, with or without
+      modifications, provided that You meet the conditions of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      shall be under the terms and conditions of this License.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages arising from the use of
+      the Work.
+
+   9. Accepting Warranty or Additional Liability. 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.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Metis contributors
+
+   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.

metis_memory-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: metis-memory
+Version: 0.1.0
+Summary: A CHAP-aligned, local-first toolkit for capturing, validating, governing, and retrieving tacit fragments as governed tacit memory for AI agents.
+Author-email: Brightbeam AI <oss@brightbeam.ai>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/BrightbeamAI/metis
+Project-URL: Documentation, https://github.com/BrightbeamAI/metis/tree/main/docs
+Project-URL: CHAP protocol, https://github.com/BrightbeamAI/chap
+Project-URL: Paper, https://www.preprints.org/manuscript/202608.0927
+Keywords: tacit-knowledge,governance,agentic-ai,memory,chap,audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chap-coordinator>=0.2.9
+Requires-Dist: pydantic>=2.5
+Requires-Dist: typer>=0.9
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: httpx>=0.24
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: uvicorn>=0.23; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: uvicorn>=0.23; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/brightbeam-logo.png" alt="Brightbeam" width="210">
+</p>
+
+<h1 align="center">Metis: Governed Tacit Memory for AI Agents</h1>
+
+<p align="center"><b>Capture how expert work actually gets done, govern it, and serve it to AI agents as memory they are allowed to use.</b></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10%2B-1f6feb">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-2ea043">
+  <img src="https://img.shields.io/badge/tests-passing-2ea043">
+  <img src="https://img.shields.io/badge/local--first-no%20cloud%20APIs-5A5A5A">
+  <img src="https://img.shields.io/badge/built%20on-CHAP-EA4700">
+</p>
+
+---
+
+AI agents now act inside real workflows, but the knowledge that makes work go right was often never
+written down. A technician hears a pump sounds wrong before any alarm. An inspector sees a batch
+"looks off" before the lab confirms it. Manuals do not capture this, and naively mining it from
+workers is unsafe and easy to get wrong.
+
+Metis is a local-first Python toolkit that captures these moments as **governed tacit
+fragments**, has a human group validate them, and serves only the validated ones to an AI agent,
+under the exact conditions where they hold, with a full audit trail. It implements the governed
+tacit-memory layer from the paper *Tacit Fragments: Operationalising Tacit Knowledge as a Governed
+Memory Layer for Agentic AI*, and it runs on [CHAP](https://github.com/BrightbeamAI/chap) so every step is recorded
+on a hash-linked, replayable evidence chain.
+
+<p align="center"><img src="docs/assets/capture_loop.svg" alt="The capture loop" width="100%"></p>
+
+## What is a tacit fragment?
+
+Most of what makes someone good at their job never reaches a document. A tacit fragment is a small,
+structured, governed record of one such piece of practice. It is deliberately partial: it is not a
+worker's whole expertise, and it is never treated as fact.
+
+Every fragment carries the things that make it safe to reuse:
+
+- **what** was observed and worker-confirmed, and its category (the K1 to K17 taxonomy of tacit knowledge),
+- **the conditions** under which it applies (site, equipment, operating mode, shift, role, risk, and exclusions),
+- **where it came from**: provenance, the worker, and their consent,
+- **the evidence** behind it (recurrence, supporting cases, counterexamples),
+- **an authority layer**: Evidence (learning only), Advisory (conditional guidance), or Controlled (formal instruction),
+- **use constraints** that travel with it.
+
+That structure is the point. A document chunk has no conditions, consent, or authority, and a
+training example is treated as ground truth. A tacit fragment is neither. It is situated guidance an
+agent may use only where it applies, and must stop using the moment it does not.
+
+## A concrete example
+
+A pump SOP says: reduce load only when the alarm threshold is crossed. Experienced operators reduce
+throughput earlier, when high load coincides with low-frequency vibration and a dull acoustic cue.
+Metis captures that gap, a human group promotes it to an advisory cue, and an agent can then use
+it, but only on the right pump in the right state.
+
+```python
+from metis import MetisEngine
+from metis.conditions.context import TacitContext
+from metis.consent.model import ConsentRecord, ConsentStatus
+
+eng = MetisEngine()              # local and deterministic, no cloud APIs
+eng.join_default_participants()
+
+# Capture what the operator does that the SOP does not say.
+frag = eng.capture_observation(
+    {
+        "observation_id": "OBS-1",
+        "work_as_imagined": "Reduce load only when the alarm threshold is crossed.",
+        "work_as_done": "Reduce throughput earlier on low-frequency vibration and a dull acoustic cue.",
+        "context": TacitContext(equipment_family="centrifugal_pump", operating_mode="high_load"),
+    },
+    consent=ConsentRecord(consent_status=ConsentStatus.granted),
+    category="K7_sensory",
+).fragment                            # lands in the Evidence layer, not yet usable
+
+# A human Mission Group promotes it. A model never makes this call.
+eng.tier2_review(frag.fragment_id, "promoted_to_advisory", summary="advisory cue only")
+
+# An agent asks for guidance. The gate returns it only when the context matches.
+match = TacitContext(equipment_family="centrifugal_pump", operating_mode="high_load", risk_class="moderate")
+other = TacitContext(equipment_family="gear_pump", operating_mode="low_load", risk_class="moderate")
+
+print(len(eng.retrieve(match).eligible))      # 1  (returned, with its use constraints)
+print(eng.retrieve(other).blocked[0].reason)  # conditions_do_not_match
+```
+
+Change the pump, raise the risk class, or withdraw consent, and the same fragment is withheld with a
+recorded reason. Retrieval is a governance decision, not a similarity search.
+
+<p align="center"><img src="docs/assets/retrieval_gate.svg" alt="The condition-aware retrieval gate" width="100%"></p>
+
+## Quickstart
+
+No cloud and no GPU. The demo and tests run without any model using deterministic fixtures.
+
+```bash
+git clone https://github.com/BrightbeamAI/metis && cd metis
+pip install -e .
+metis demo manufacturing-pump-vibration
+```
+
+The installable package name is `metis-memory` (import `metis`, CLI `metis`). The official
+[`chap-coordinator`](https://pypi.org/project/chap-coordinator/) dependency installs from PyPI
+automatically.
+
+The demo runs the whole flow locally and writes a replayable evidence chain. Inspect it with
+`metis fragment list`, `metis memory list`, `metis retrieve --context <file>`, and
+`metis audit read`.
+
+Prefer to click through it? Open the **[interactive demo](docs/demo.html)**: pick a scenario, step
+through the loop, and drive the gate yourself by editing the context and watching it allow or block.
+For a guided tour, open the illustrated **[explainer](docs/explainer.html)**.
+
+## How it works
+
+**Capture loop.** Observe a work event, infer a candidate (a hypothesis, never trusted), whisper one
+short bounded question to the worker, confirm with them (descriptive fidelity only), and remember the
+result as an Evidence-layer fragment.
+
+**Governance.** A human Mission Group reviews each fragment across fidelity, operational relevance,
+normative alignment, and risk, then promotes it to Advisory or Controlled, or holds, rejects, or
+re-elicits it. Evidence-layer fragments can never drive a decision or reach an agent. A local model
+may draft a review summary, but it never decides.
+
+**Memory and retrieval.** A promoted fragment becomes a governed memory object. A broker assembles an
+agent context from procedural, semantic, episodic, and tacit memory, and tacit memory is reached only
+through the condition-aware gate, which carries the use constraints with it.
+
+## Learn more
+
+- **[Interactive demo](docs/demo.html)** and **[explainer](docs/explainer.html)**: the fastest way to get it.
+- **[Documentation](docs/README.md)**: architecture, governance, retrieval, the K1 to K17 taxonomy, agent use.
+- **[ABOUT.md](ABOUT.md)**: repository map, the four memory stores, the CHAP relationship, and how to develop.
+- **[CHAP](https://github.com/BrightbeamAI/chap)**: the protocol Metis runs on.
+
+## Ethical use
+
+Metis captures fragments of human work. Do not use it for covert worker monitoring. It records no
+audio, video, biometrics, screenshots, or keystrokes, fragments are never treated as fact, and the
+audit chain is append-only. Production use needs worker consultation, legal review, and domain
+validation. Read [ETHICAL_USE.md](ETHICAL_USE.md) first.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).
+
+## Citation
+
+Metis is the reference implementation for the paper *Tacit Fragments: Operationalising Tacit
+Knowledge as a Governed Memory Layer for Agentic AI*
+([preprint](https://www.preprints.org/manuscript/202608.0927), also included in this repository as
+[docs/tacit_fragments_preprint.pdf](docs/tacit_fragments_preprint.pdf)). If you use Metis in
+research, please cite:
+
+```bibtex
+@article{shahid2026tacitfragments,
+  title   = {Tacit Fragments: Operationalising Tacit Knowledge as a Governed Memory Layer for Agentic AI},
+  author  = {Shahid, Arsalan and Suttie, Gordon and Black, Philip and Garz{\'o}n-Vico, Antonio},
+  journal = {Preprints},
+  year    = {2026},
+  doi     = {10.20944/preprints202608.0927.v1},
+  url     = {https://www.preprints.org/manuscript/202608.0927}
+}
+```

metis_memory-0.1.0/README.md

@@ -0,0 +1,167 @@
+<p align="center">
+  <img src="docs/assets/brightbeam-logo.png" alt="Brightbeam" width="210">
+</p>
+
+<h1 align="center">Metis: Governed Tacit Memory for AI Agents</h1>
+
+<p align="center"><b>Capture how expert work actually gets done, govern it, and serve it to AI agents as memory they are allowed to use.</b></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.10%2B-1f6feb">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-2ea043">
+  <img src="https://img.shields.io/badge/tests-passing-2ea043">
+  <img src="https://img.shields.io/badge/local--first-no%20cloud%20APIs-5A5A5A">
+  <img src="https://img.shields.io/badge/built%20on-CHAP-EA4700">
+</p>
+
+---
+
+AI agents now act inside real workflows, but the knowledge that makes work go right was often never
+written down. A technician hears a pump sounds wrong before any alarm. An inspector sees a batch
+"looks off" before the lab confirms it. Manuals do not capture this, and naively mining it from
+workers is unsafe and easy to get wrong.
+
+Metis is a local-first Python toolkit that captures these moments as **governed tacit
+fragments**, has a human group validate them, and serves only the validated ones to an AI agent,
+under the exact conditions where they hold, with a full audit trail. It implements the governed
+tacit-memory layer from the paper *Tacit Fragments: Operationalising Tacit Knowledge as a Governed
+Memory Layer for Agentic AI*, and it runs on [CHAP](https://github.com/BrightbeamAI/chap) so every step is recorded
+on a hash-linked, replayable evidence chain.
+
+<p align="center"><img src="docs/assets/capture_loop.svg" alt="The capture loop" width="100%"></p>
+
+## What is a tacit fragment?
+
+Most of what makes someone good at their job never reaches a document. A tacit fragment is a small,
+structured, governed record of one such piece of practice. It is deliberately partial: it is not a
+worker's whole expertise, and it is never treated as fact.
+
+Every fragment carries the things that make it safe to reuse:
+
+- **what** was observed and worker-confirmed, and its category (the K1 to K17 taxonomy of tacit knowledge),
+- **the conditions** under which it applies (site, equipment, operating mode, shift, role, risk, and exclusions),
+- **where it came from**: provenance, the worker, and their consent,
+- **the evidence** behind it (recurrence, supporting cases, counterexamples),
+- **an authority layer**: Evidence (learning only), Advisory (conditional guidance), or Controlled (formal instruction),
+- **use constraints** that travel with it.
+
+That structure is the point. A document chunk has no conditions, consent, or authority, and a
+training example is treated as ground truth. A tacit fragment is neither. It is situated guidance an
+agent may use only where it applies, and must stop using the moment it does not.
+
+## A concrete example
+
+A pump SOP says: reduce load only when the alarm threshold is crossed. Experienced operators reduce
+throughput earlier, when high load coincides with low-frequency vibration and a dull acoustic cue.
+Metis captures that gap, a human group promotes it to an advisory cue, and an agent can then use
+it, but only on the right pump in the right state.
+
+```python
+from metis import MetisEngine
+from metis.conditions.context import TacitContext
+from metis.consent.model import ConsentRecord, ConsentStatus
+
+eng = MetisEngine()              # local and deterministic, no cloud APIs
+eng.join_default_participants()
+
+# Capture what the operator does that the SOP does not say.
+frag = eng.capture_observation(
+    {
+        "observation_id": "OBS-1",
+        "work_as_imagined": "Reduce load only when the alarm threshold is crossed.",
+        "work_as_done": "Reduce throughput earlier on low-frequency vibration and a dull acoustic cue.",
+        "context": TacitContext(equipment_family="centrifugal_pump", operating_mode="high_load"),
+    },
+    consent=ConsentRecord(consent_status=ConsentStatus.granted),
+    category="K7_sensory",
+).fragment                            # lands in the Evidence layer, not yet usable
+
+# A human Mission Group promotes it. A model never makes this call.
+eng.tier2_review(frag.fragment_id, "promoted_to_advisory", summary="advisory cue only")
+
+# An agent asks for guidance. The gate returns it only when the context matches.
+match = TacitContext(equipment_family="centrifugal_pump", operating_mode="high_load", risk_class="moderate")
+other = TacitContext(equipment_family="gear_pump", operating_mode="low_load", risk_class="moderate")
+
+print(len(eng.retrieve(match).eligible))      # 1  (returned, with its use constraints)
+print(eng.retrieve(other).blocked[0].reason)  # conditions_do_not_match
+```
+
+Change the pump, raise the risk class, or withdraw consent, and the same fragment is withheld with a
+recorded reason. Retrieval is a governance decision, not a similarity search.
+
+<p align="center"><img src="docs/assets/retrieval_gate.svg" alt="The condition-aware retrieval gate" width="100%"></p>
+
+## Quickstart
+
+No cloud and no GPU. The demo and tests run without any model using deterministic fixtures.
+
+```bash
+git clone https://github.com/BrightbeamAI/metis && cd metis
+pip install -e .
+metis demo manufacturing-pump-vibration
+```
+
+The installable package name is `metis-memory` (import `metis`, CLI `metis`). The official
+[`chap-coordinator`](https://pypi.org/project/chap-coordinator/) dependency installs from PyPI
+automatically.
+
+The demo runs the whole flow locally and writes a replayable evidence chain. Inspect it with
+`metis fragment list`, `metis memory list`, `metis retrieve --context <file>`, and
+`metis audit read`.
+
+Prefer to click through it? Open the **[interactive demo](docs/demo.html)**: pick a scenario, step
+through the loop, and drive the gate yourself by editing the context and watching it allow or block.
+For a guided tour, open the illustrated **[explainer](docs/explainer.html)**.
+
+## How it works
+
+**Capture loop.** Observe a work event, infer a candidate (a hypothesis, never trusted), whisper one
+short bounded question to the worker, confirm with them (descriptive fidelity only), and remember the
+result as an Evidence-layer fragment.
+
+**Governance.** A human Mission Group reviews each fragment across fidelity, operational relevance,
+normative alignment, and risk, then promotes it to Advisory or Controlled, or holds, rejects, or
+re-elicits it. Evidence-layer fragments can never drive a decision or reach an agent. A local model
+may draft a review summary, but it never decides.
+
+**Memory and retrieval.** A promoted fragment becomes a governed memory object. A broker assembles an
+agent context from procedural, semantic, episodic, and tacit memory, and tacit memory is reached only
+through the condition-aware gate, which carries the use constraints with it.
+
+## Learn more
+
+- **[Interactive demo](docs/demo.html)** and **[explainer](docs/explainer.html)**: the fastest way to get it.
+- **[Documentation](docs/README.md)**: architecture, governance, retrieval, the K1 to K17 taxonomy, agent use.
+- **[ABOUT.md](ABOUT.md)**: repository map, the four memory stores, the CHAP relationship, and how to develop.
+- **[CHAP](https://github.com/BrightbeamAI/chap)**: the protocol Metis runs on.
+
+## Ethical use
+
+Metis captures fragments of human work. Do not use it for covert worker monitoring. It records no
+audio, video, biometrics, screenshots, or keystrokes, fragments are never treated as fact, and the
+audit chain is append-only. Production use needs worker consultation, legal review, and domain
+validation. Read [ETHICAL_USE.md](ETHICAL_USE.md) first.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).
+
+## Citation
+
+Metis is the reference implementation for the paper *Tacit Fragments: Operationalising Tacit
+Knowledge as a Governed Memory Layer for Agentic AI*
+([preprint](https://www.preprints.org/manuscript/202608.0927), also included in this repository as
+[docs/tacit_fragments_preprint.pdf](docs/tacit_fragments_preprint.pdf)). If you use Metis in
+research, please cite:
+
+```bibtex
+@article{shahid2026tacitfragments,
+  title   = {Tacit Fragments: Operationalising Tacit Knowledge as a Governed Memory Layer for Agentic AI},
+  author  = {Shahid, Arsalan and Suttie, Gordon and Black, Philip and Garz{\'o}n-Vico, Antonio},
+  journal = {Preprints},
+  year    = {2026},
+  doi     = {10.20944/preprints202608.0927.v1},
+  url     = {https://www.preprints.org/manuscript/202608.0927}
+}
+```

metis_memory-0.1.0/metis/__init__.py

@@ -0,0 +1,16 @@
+"""Metis, a reference toolkit for governed tacit fragment capture.
+
+Metis captures situated human practice as partial, validated, context-bound fragments
+tied to provenance, consent, authority, review state, and retrieval constraints, and turns
+validated fragments into governed tacit memory objects that AI agents can use alongside
+procedural, semantic, and episodic memory, exposed only through condition-aware governance
+gates. It uses local Ollama/Gemma models for bounded assistance and CHAP as its protocol
+foundation.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .engine import MetisEngine
+
+__all__ = ["MetisEngine", "__version__"]

metis_memory-0.1.0/metis/api/__init__.py

@@ -0,0 +1,6 @@
+"""Optional local FastAPI server for Metis (install the ``api`` extra)."""
+try:
+    from .server import app, create_app
+    __all__ = ["app", "create_app"]
+except Exception:  # fastapi not installed
+    __all__ = []

metis_memory-0.1.0/metis/api/routes.py

@@ -0,0 +1,167 @@
+"""FastAPI routes over the same engine, models, and evidence logic as the CLI.
+
+Optional component (install with the ``api`` extra). Governance remains deterministic and
+human-reviewed; nothing here lets a model or an agent promote or authorise a fragment.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from ..conditions.context import TacitContext
+from ..consent.model import ConsentRecord, ConsentStatus
+from ..consent.revocation import RevocationReason
+from ..engine import MetisEngine
+from ..scenarios import run_manufacturing
+
+router = APIRouter()
+
+# A single in-memory engine, seeded with the manufacturing scenario for immediate data.
+ENGINE = run_manufacturing().engine
+
+
+def reset_engine(engine: MetisEngine | None = None) -> None:
+    global ENGINE
+    ENGINE = engine or run_manufacturing().engine
+
+
+class CaptureRequest(BaseModel):
+    observation_id: str
+    work_as_imagined: str | None = None
+    work_as_done: str | None = None
+    text: str | None = None
+    context: dict[str, Any] = {}
+    category: str | None = None
+    response: str = "confirm"
+    corrected_content: str | None = None
+    title: str | None = None
+
+
+class ReviewRequest(BaseModel):
+    fragment_id: str
+    outcome: str
+    summary: str = ""
+    change_control: dict[str, Any] | None = None
+
+
+class ContextRequest(BaseModel):
+    context: dict[str, Any]
+    role: str | None = None
+    task_id: str = "tsk_api_query"
+
+
+class RevokeRequest(BaseModel):
+    fragment_id: str
+    reason: str = "retired"
+    by: str = "human:reviewer@plant_a"
+
+
+@router.get("/workspace")
+def get_workspace() -> dict[str, Any]:
+    return ENGINE.adapter.descriptor()
+
+
+@router.get("/fragments")
+def list_fragments() -> list[dict[str, Any]]:
+    return [f.model_dump(mode="json") for f in ENGINE.fragments.all()]
+
+
+@router.get("/fragments/{fragment_id}")
+def get_fragment(fragment_id: str) -> dict[str, Any]:
+    frag = ENGINE.fragments.get(fragment_id)
+    if not frag:
+        raise HTTPException(404, "fragment not found")
+    return frag.model_dump(mode="json")
+
+
+@router.get("/memory")
+def list_memory() -> list[dict[str, Any]]:
+    return [m.model_dump(mode="json") for m in ENGINE.tacit_store.all()]
+
+
+@router.get("/memory/{memory_id}")
+def get_memory(memory_id: str) -> dict[str, Any]:
+    m = ENGINE.tacit_store.get(memory_id)
+    if not m:
+        raise HTTPException(404, "memory object not found")
+    return m.model_dump(mode="json")
+
+
+@router.post("/memory/query")
+def memory_query(req: ContextRequest) -> dict[str, Any]:
+    amc = ENGINE.agent_context(req.task_id, TacitContext.model_validate(req.context), role=req.role, emit=True)
+    return amc.model_dump(mode="json")
+
+
+@router.post("/capture")
+def capture(req: CaptureRequest) -> dict[str, Any]:
+    consent = ConsentRecord(consent_status=ConsentStatus.granted)
+    result = ENGINE.capture_observation(
+        dict(observation_id=req.observation_id, work_as_imagined=req.work_as_imagined,
+             work_as_done=req.work_as_done, text=req.text,
+             context=TacitContext.model_validate(req.context), source="api"),
+        consent=consent, response=req.response, corrected_content=req.corrected_content,
+        category=req.category, title=req.title,
+        conditions=TacitContext.model_validate(req.context))
+    return {"fragment": result.fragment.model_dump(mode="json") if result.fragment else None,
+            "task_id": result.task_id,
+            "model_assist_records": [a.assist_id for a in result.model_assist_records]}
+
+
+@router.post("/confirm")
+def confirm(req: CaptureRequest) -> dict[str, Any]:
+    """Confirmation is captured as part of the loop; this is an alias for /capture."""
+    return capture(req)
+
+
+@router.post("/review")
+def review(req: ReviewRequest) -> dict[str, Any]:
+    out = ENGINE.tier2_review(req.fragment_id, req.outcome, summary=req.summary,
+                              change_control=req.change_control)
+    return {"outcome": req.outcome, "memory_id": out.get("memory").memory_id if out.get("memory") else None}
+
+
+@router.post("/promote")
+def promote(req: ReviewRequest) -> dict[str, Any]:
+    if req.outcome not in ("promoted_to_advisory", "promoted_to_controlled"):
+        req.outcome = "promoted_to_advisory"
+    return review(req)
+
+
+@router.post("/retrieve")
+def retrieve(req: ContextRequest) -> dict[str, Any]:
+    decision = ENGINE.retrieve(TacitContext.model_validate(req.context), role=req.role)
+    return decision.model_dump(mode="json")
+
+
+@router.post("/revoke")
+def revoke(req: RevokeRequest) -> dict[str, Any]:
+    art = ENGINE.governance.revoke(req.fragment_id, reason=RevocationReason(req.reason), by=req.by)
+    return {"revocation_record_artefact": art}
+
+
+@router.get("/audit")
+def audit() -> list[dict[str, Any]]:
+    return ENGINE.adapter.evidence_records()
+
+
+@router.post("/audit/export")
+def audit_export(out: str = "evidence.jsonl") -> dict[str, Any]:
+    n = ENGINE.export_audit(out)
+    return {"exported": n, "path": out, "verified": ENGINE.verify().ok}
+
+
+@router.get("/model/status")
+def model_status() -> dict[str, Any]:
+    c = ENGINE.model_client
+    return {"provider": c.config.provider, "model": c.config.name, "url": c.config.url,
+            "available": c.available()}
+
+
+@router.post("/model/run")
+def model_run(prompt: str, purpose: str = "draft_whisper") -> dict[str, Any]:
+    res = ENGINE.model_client.run(purpose, prompt)
+    return {"used_live_model": res.used_live_model, "output": res.json(),
+            "note": "advisory draft only; not a governance decision"}

metis_memory-0.1.0/metis/api/server.py

@@ -0,0 +1,19 @@
+"""Local FastAPI server. Run: ``uvicorn metis.api.server:app``. Optional component."""
+from __future__ import annotations
+
+
+def create_app():
+    from fastapi import FastAPI
+
+    from .routes import router
+
+    application = FastAPI(
+        title="Metis",
+        description="Governed tacit fragment capture, local-first, CHAP-aligned. "
+                    "Tacit memory is exposed only through condition-aware governance gates.",
+        version="0.1.0")
+    application.include_router(router)
+    return application
+
+
+app = create_app()