open-refinery 0.1.0__py3-none-any.whl

open_refinery/__init__.py

@@ -0,0 +1,22 @@
+"""open-refinery — a factory for producing artifacts under governance."""
+
+from .audit import AuditSink, JsonlSink, MemorySink
+from .authz import AllowAll, AllowList, Authorizer, Unauthorized
+from .factory import Factory, UnknownRecipe
+from .provenance import Record
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Factory",
+    "UnknownRecipe",
+    "Record",
+    "Authorizer",
+    "AllowAll",
+    "AllowList",
+    "Unauthorized",
+    "AuditSink",
+    "MemorySink",
+    "JsonlSink",
+    "__version__",
+]

open_refinery/audit.py

@@ -0,0 +1,35 @@
+"""Audit sink — append-only trail of production events."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+from .provenance import Record
+
+
+class AuditSink(Protocol):
+    def write(self, record: Record) -> None: ...
+
+
+class MemorySink:
+    """In-memory trail. Default; useful for tests and ephemeral runs."""
+
+    def __init__(self) -> None:
+        self.records: list[Record] = []
+
+    def write(self, record: Record) -> None:
+        self.records.append(record)
+
+
+class JsonlSink:
+    """Append each record as one JSON line. The durable audit trail."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def write(self, record: Record) -> None:
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(record.to_dict(), sort_keys=True) + "\n")

open_refinery/authz.py

@@ -0,0 +1,30 @@
+"""Authorization — the gate checked before a recipe runs."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class Unauthorized(Exception):
+    """Raised when an actor may not run a recipe."""
+
+
+class Authorizer(Protocol):
+    def allows(self, actor: str, recipe: str) -> bool: ...
+
+
+class AllowAll:
+    """Default authorizer — permits every actor. Replace in production."""
+
+    def allows(self, actor: str, recipe: str) -> bool:
+        return True
+
+
+class AllowList:
+    """Permit only (actor, recipe) pairs present in the grant set."""
+
+    def __init__(self, grants: set[tuple[str, str]]) -> None:
+        self._grants = grants
+
+    def allows(self, actor: str, recipe: str) -> bool:
+        return (actor, recipe) in self._grants

open_refinery/cli.py

@@ -0,0 +1,33 @@
+"""Demo CLI — produces one artifact and prints its provenance record."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+
+from .factory import Factory
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="open-refinery")
+    parser.add_argument("--actor", default="demo-user")
+    parser.add_argument("--text", default="hello", help="text to refine")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    factory = Factory()
+
+    @factory.recipe("upper")
+    def upper(text: str) -> str:
+        return text.upper()
+
+    artifact, record = factory.produce("upper", actor=args.actor, text=args.text)
+    print(f"artifact: {artifact!r}")
+    print(json.dumps(record.to_dict(), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

open_refinery/factory.py

@@ -0,0 +1,73 @@
+"""Factory — produces artifacts, wrapping each output in governance."""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+from .audit import AuditSink, MemorySink
+from .authz import AllowAll, Authorizer, Unauthorized
+from .provenance import Record
+
+log = logging.getLogger("open_refinery")
+
+Recipe = Callable[..., object]
+
+
+class UnknownRecipe(KeyError):
+    """Raised when producing from an unregistered recipe."""
+
+
+class Factory:
+    """Registers recipes and produces artifacts under governance.
+
+    Every ``produce`` call is authorized, run, recorded with provenance and
+    ownership, and appended to the audit trail — in that order.
+    """
+
+    def __init__(
+        self,
+        authorizer: Authorizer | None = None,
+        audit: AuditSink | None = None,
+    ) -> None:
+        self._recipes: dict[str, Recipe] = {}
+        self._authorizer = authorizer or AllowAll()
+        self._audit = audit or MemorySink()
+
+    def register(self, name: str, recipe: Recipe) -> None:
+        self._recipes[name] = recipe
+
+    def recipe(self, name: str) -> Callable[[Recipe], Recipe]:
+        """Decorator form of :meth:`register`."""
+
+        def decorate(fn: Recipe) -> Recipe:
+            self.register(name, fn)
+            return fn
+
+        return decorate
+
+    def produce(
+        self,
+        name: str,
+        *,
+        actor: str,
+        owner: str | None = None,
+        **inputs: object,
+    ) -> tuple[object, Record]:
+        if name not in self._recipes:
+            raise UnknownRecipe(name)
+        if not self._authorizer.allows(actor, name):
+            raise Unauthorized(f"{actor} may not run {name}")
+
+        owner = owner or actor
+        artifact = self._recipes[name](**inputs)
+        record = Record.of(name, actor, owner, inputs, artifact)
+        self._audit.write(record)
+        log.info(
+            "produced recipe=%s artifact=%s actor=%s owner=%s",
+            name,
+            record.artifact_id,
+            actor,
+            owner,
+        )
+        return artifact, record

open_refinery/provenance.py

@@ -0,0 +1,44 @@
+"""Provenance record — the governance metadata attached to every produced artifact."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+
+
+def _digest(value: object) -> str:
+    """Stable SHA-256 of any JSON-serializable value; repr fallback for the rest."""
+    try:
+        payload = json.dumps(value, sort_keys=True, default=repr)
+    except TypeError:
+        payload = repr(value)
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class Record:
+    """Immutable provenance for a single production event."""
+
+    recipe: str
+    actor: str
+    owner: str
+    input_digest: str
+    output_digest: str
+    artifact_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    @classmethod
+    def of(cls, recipe: str, actor: str, owner: str, inputs: dict, output: object) -> Record:
+        return cls(
+            recipe=recipe,
+            actor=actor,
+            owner=owner,
+            input_digest=_digest(inputs),
+            output_digest=_digest(output),
+        )
+
+    def to_dict(self) -> dict:
+        return asdict(self)

open_refinery-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: open-refinery
+Version: 0.1.0
+Summary: A factory for producing artifacts under governance — provenance, ownership, authorization, and an append-only audit trail on every output.
+Project-URL: Homepage, https://github.com/tacoda/open-refinery
+Project-URL: Repository, https://github.com/tacoda/open-refinery
+Author-email: Ian Johnson <ian@tacoda.dev>
+License: MIT
+License-File: LICENSE
+Keywords: audit,factory,governance,observability,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# open-refinery
+
+A factory for producing artifacts under governance. Every output carries its
+**provenance**, an **owner**, and an **audit trail**; every production is
+**authorized** before it runs and **logged** as it happens.
+
+> Status: **0.1.0 — proof of concept.** The core loop (authorize → produce →
+> record → audit) is real and tested. Policy-based governance, richer
+> observability, and pluggable sinks are on the roadmap.
+
+## Install
+
+```bash
+uv add open-refinery       # or: pip install open-refinery
+```
+
+## Use
+
+```python
+from open_refinery import Factory
+
+factory = Factory()
+
+@factory.recipe("upper")
+def upper(text: str) -> str:
+    return text.upper()
+
+artifact, record = factory.produce("upper", actor="ian", text="hello")
+# artifact -> "HELLO"
+# record   -> Record(recipe="upper", actor="ian", owner="ian",
+#                    artifact_id=..., input_digest=..., output_digest=..., created_at=...)
+```
+
+Try the demo CLI:
+
+```bash
+uv run open-refinery --actor ian --text hello
+```
+
+## Pillars
+
+| Pillar          | Where it lives                                              |
+|-----------------|-------------------------------------------------------------|
+| Authorization   | `Authorizer` (`AllowAll`, `AllowList`) — checked before produce |
+| Provenance      | `Record` — recipe, actor, timestamp, input/output digests   |
+| Ownership       | `owner` on every record (defaults to the actor)             |
+| Auditability    | `AuditSink` (`MemorySink`, `JsonlSink`) — append-only trail  |
+| Logging         | stdlib `logging`, logger name `open_refinery`               |
+| Observability   | *(roadmap)* read-model / metrics over the audit trail       |
+| Governance      | *(roadmap)* policy layer that constrains what may be produced |
+
+## Durable audit trail
+
+```python
+from open_refinery import Factory, JsonlSink
+
+factory = Factory(audit=JsonlSink("audit.jsonl"))
+```
+
+Each production appends one JSON line — a replayable record of who produced
+what, from which inputs, and when.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## License
+
+[MIT](LICENSE) © Ian Johnson

open_refinery-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+open_refinery/__init__.py,sha256=lhwREQ2MS0Z3p2SaErwp1KD2OpB_Rkn4TwfKmAbwMys,499
+open_refinery/audit.py,sha256=NpK-qR6qxmgeHty5I625v2qhyGVVSuDve22bFouetdc,932
+open_refinery/authz.py,sha256=IrB40i0pB2BjAA241QoEhEvUKuTho0mRokVLQ_oojy0,759
+open_refinery/cli.py,sha256=9ibkkGsxvZ9Jx2hlHj74wRWpUMiwW5XA0AdXhDH68zI,899
+open_refinery/factory.py,sha256=N9LoFo67cIB9Ko6WGnbICjGSYvITdBqIW1qmlYkjHY0,2055
+open_refinery/provenance.py,sha256=-p-fbdr_X9CB98Z4uY5OXYftl6K5Zi-7JCX74Z_3y9k,1280
+open_refinery-0.1.0.dist-info/METADATA,sha256=2QsF_tLAjbNhE3qCqg4Ak_UCj4GUII4iEa5hI6ufrdE,3067
+open_refinery-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+open_refinery-0.1.0.dist-info/entry_points.txt,sha256=_zQm8vxboggTwoCl26M0_WAqcMU5EmcT7nZrGFTYaSU,57
+open_refinery-0.1.0.dist-info/licenses/LICENSE,sha256=letU8CJjd8PcS8eMmUx6RVzrmzVEaYmFmtRtuJVrKHI,1068
+open_refinery-0.1.0.dist-info/RECORD,,

open_refinery-0.1.0.dist-info/WHEEL

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

open_refinery-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+open-refinery = open_refinery.cli:main

open_refinery-0.1.0.dist-info/licenses/LICENSE

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