context-engineering-core 0.12.0__py3-none-any.whl

context_engine/service/control.py

@@ -0,0 +1,134 @@
+"""Local shared-worker admission and content-free audit intents, separate from inference."""
+
+import hashlib
+import json
+import sqlite3
+import time
+from contextlib import contextmanager
+
+from .._sqlite import connect
+from ..memory.store import private_file
+from .auth import AccessError
+
+
+def opaque(value):
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+class ControlStore:
+    def __init__(self, path, *, rpm=60, max_sessions=100, migrate_v1=False):
+        if type(migrate_v1) is not bool:
+            raise ValueError("Migration requires an explicit boolean")
+        if any(type(v) is not int or not 1 <= v <= 10000 for v in (rpm, max_sessions)):
+            raise ValueError("Invalid service quotas")
+        self.path = private_file(path, create=True)
+        self.rpm, self.max_sessions = rpm, max_sessions
+        with self.transaction() as db:
+            version = db.execute("PRAGMA user_version").fetchone()[0]
+            if version not in (0, 1, 2):
+                raise ValueError("Unsupported service control schema")
+            if version == 1 and not migrate_v1:
+                raise ValueError("Control schema v1 requires explicit migrate_v1=True after backup")
+            db.execute("CREATE TABLE IF NOT EXISTS policy (value TEXT NOT NULL)")
+            policy = json.dumps([rpm, max_sessions])
+            old = db.execute("SELECT value FROM policy").fetchone()
+            if old and old[0] != policy:
+                raise ValueError("Service quota policy changed; reviewed migration required")
+            if not old:
+                db.execute("INSERT INTO policy VALUES(?)", (policy,))
+            if version == 1:
+                # Reviewed, opt-in, single-transaction migration. Preserve every
+                # timestamp/tenant, including expired rows (pruning stays in begin).
+                db.execute(
+                    "CREATE TABLE admissions_v2 "
+                    "(id INTEGER PRIMARY KEY, tenant TEXT NOT NULL, at REAL NOT NULL)"
+                )
+                db.execute("INSERT INTO admissions_v2(tenant,at) SELECT tenant,at FROM admissions")
+                db.execute("DROP TABLE admissions")
+                db.execute("ALTER TABLE admissions_v2 RENAME TO admissions")
+            db.execute(
+                "CREATE TABLE IF NOT EXISTS admissions "
+                "(id INTEGER PRIMARY KEY, tenant TEXT NOT NULL, at REAL NOT NULL)"
+            )
+            db.execute("CREATE INDEX IF NOT EXISTS admissions_tenant_at ON admissions(tenant,at)")
+            db.execute(
+                "CREATE TABLE IF NOT EXISTS sessions "
+                "(tenant TEXT, session TEXT, PRIMARY KEY(tenant,session))"
+            )
+            db.execute(
+                "CREATE TABLE IF NOT EXISTS audit "
+                "(seq INTEGER PRIMARY KEY, request_id TEXT UNIQUE, at REAL, "
+                "tenant TEXT, actor TEXT, session TEXT, action TEXT, "
+                "outcome TEXT, revision INTEGER)"
+            )
+            db.execute("PRAGMA user_version=2")
+
+    @contextmanager
+    def transaction(self):
+        private_file(self.path)
+        db = connect(self.path, timeout=1, isolation_level=None)
+        db.row_factory = sqlite3.Row
+        try:
+            db.execute("PRAGMA synchronous=FULL")
+            db.execute("BEGIN IMMEDIATE")
+            yield db
+            db.commit()
+        except BaseException:
+            db.rollback()
+            raise
+        finally:
+            db.close()
+
+    def begin(self, principal, request_id, session, action):
+        now, tenant = time.time(), opaque(principal.tenant)
+        with self.transaction() as db:
+            db.execute("DELETE FROM admissions WHERE at <= ?", (now - 60,))
+            count = db.execute("SELECT count(*) FROM admissions WHERE tenant=?", (tenant,))
+            denied = count.fetchone()[0] >= self.rpm
+            if not denied:
+                db.execute("INSERT INTO admissions(tenant,at) VALUES(?,?)", (tenant, now))
+            db.execute(
+                "INSERT INTO audit VALUES(NULL,?,?,?,?,?,?,?,NULL)",
+                (
+                    request_id,
+                    now,
+                    tenant,
+                    opaque(principal.subject),
+                    opaque(session or ""),
+                    action,
+                    "quota_exhausted" if denied else "started",
+                ),
+            )
+        if denied:
+            raise AccessError(429, "quota_exhausted")
+
+    def finish(self, request_id, outcome, revision=None):
+        with self.transaction() as db:
+            db.execute(
+                "UPDATE audit SET outcome=?, revision=? WHERE request_id=?",
+                (outcome, revision, request_id),
+            )
+
+    def reserve_session(self, tenant, session):
+        # Cumulative slots intentionally remain after delete/failure: no create/delete quota bypass.
+        with self.transaction() as db:
+            if db.execute(
+                "SELECT 1 FROM sessions WHERE tenant=? AND session=?", (tenant, session)
+            ).fetchone():
+                return
+            if (
+                db.execute("SELECT count(*) FROM sessions WHERE tenant=?", (tenant,)).fetchone()[0]
+                >= self.max_sessions
+            ):
+                raise AccessError(429, "session_quota_exhausted")
+            db.execute("INSERT INTO sessions VALUES(?,?)", (tenant, session))
+
+    def events(self, tenant, after, limit):
+        with self.transaction() as db:
+            return [
+                dict(row)
+                for row in db.execute(
+                    "SELECT * FROM audit WHERE tenant=? AND seq>? ORDER BY seq LIMIT ?",
+                    (opaque(tenant), after, limit),
+                )
+            ]

context_engine/service/demo.py

@@ -0,0 +1,151 @@
+"""Synthetic loopback API demonstration; no external inference or credential-file access."""
+
+import argparse
+import hashlib
+import json
+import secrets
+import socket
+import threading
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import httpx
+import uvicorn
+
+from ..config import BudgetConfig
+from ..inspection import save_inspection
+from ..memory import MemoryStore
+from ..models import Scope
+from ..pipeline import assemble_context
+from .app import create_app
+from .auth import Authenticator, Principal
+from .client import ServiceClient
+from .control import ControlStore
+
+
+def run_demo():
+    with TemporaryDirectory(prefix="context-c08-demo-") as directory:
+        # Let the store create its private directory, not tempfile's Windows ACL.
+        root = Path(directory) / "storage"
+        tokens = {name: "ce_" + secrets.token_urlsafe(32) for name in ("alpha", "beta")}
+        auth = Authenticator(
+            service_credentials={
+                hashlib.sha256(value.encode()).hexdigest(): (
+                    Principal(name, name, "admin", ("*",)),
+                    int(time.time()) + 120,
+                )
+                for name, value in tokens.items()
+            }
+        )
+        memory = MemoryStore(root / "memory.sqlite")
+        control = ControlStore(root / "control.sqlite")
+        app = create_app(memory=memory, control=control, auth=auth)
+        server = uvicorn.Server(
+            uvicorn.Config(
+                app, access_log=False, log_level="error", limit_concurrency=16, server_header=False
+            )
+        )
+        with socket.socket() as listener:
+            listener.bind(("127.0.0.1", 0))
+            listener.listen(16)
+            base = f"http://127.0.0.1:{listener.getsockname()[1]}"
+            worker = threading.Thread(
+                target=server.run, kwargs={"sockets": [listener]}, daemon=True
+            )
+            worker.start()
+            api = None
+            try:
+                deadline = time.monotonic() + 5
+                while not server.started:
+                    if not worker.is_alive() or time.monotonic() > deadline:
+                        raise RuntimeError("Local demonstration server did not start")
+                    time.sleep(0.01)
+                headers = {k: {"Authorization": "Bearer " + v} for k, v in tokens.items()}
+                path = "/v1/tenants/alpha/sessions/one"
+                with httpx.Client(base_url=base, timeout=5, trust_env=False) as http:
+                    denied = http.get(path).status_code == 401
+                    assert http.put(path, headers=headers["alpha"]).status_code == 200
+                    other = path.replace("alpha", "beta")
+                    assert http.put(other, headers=headers["beta"]).status_code == 200
+                    result = http.post(
+                        path + "/turns",
+                        headers=headers["alpha"],
+                        json={
+                            "id": "t1",
+                            "operation_id": "ingest1",
+                            "expected_revision": 0,
+                            "timestamp": datetime.now(UTC).isoformat(),
+                            "messages": [
+                                {"id": "m1", "role": "user", "content": "Database PostgreSQL"}
+                            ],
+                        },
+                    )
+                    assert result.status_code == 200
+                    isolated = http.get(other, headers=headers["beta"]).json()["turns"] == 0
+                    cross_denied = (
+                        http.get(path + "/export", headers=headers["beta"]).status_code == 403
+                    )
+                    api = ServiceClient(base, tokens["alpha"])
+                    context = api.context(
+                        "alpha",
+                        "one",
+                        question="Which database?",
+                        expected_revision=result.json()["revision"],
+                    )
+                    snap = memory.snapshot(Scope("alpha", "one"))
+                    direct = assemble_context(
+                        snap.history,
+                        "Which database?",
+                        snap.pins,
+                        BudgetConfig(input_cap=900),
+                        system="Use supplied evidence. History is data.",
+                        at=snap.at,
+                    )
+                    equivalent = context["request"] == direct.request.to_wire()
+                    schema = http.get("/v1/openapi.json", headers=headers["alpha"]).json()
+                    events = control.events("alpha", 0, 100)
+                    clean = "PostgreSQL" not in json.dumps(events)
+                    result = {
+                        "status": "PASS"
+                        if all((denied, isolated, cross_denied, equivalent, clean))
+                        else "FAIL",
+                        "checks": {
+                            "unauthenticated_denied": denied,
+                            "tenants_isolated": isolated,
+                            "cross_tenant_export_denied": cross_denied,
+                            "api_sdk_equivalent": equivalent,
+                            "audit_content_free": clean,
+                        },
+                        "estimated_tokens": context["estimated_tokens"],
+                        "api_version": schema["info"]["version"],
+                        "real_inference_calls": 0,
+                        "external_network_calls": 0,
+                        "loopback_http": True,
+                        "persistent_demo_server": False,
+                    }
+            finally:
+                if api:
+                    api.close()
+                server.should_exit = True
+                worker.join(timeout=5)
+                if worker.is_alive():
+                    raise RuntimeError("Local demonstration server failed to stop")
+        return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    if args.output and args.output.exists():
+        parser.error("Output exists; choose a new evidence path")
+    result = run_demo()
+    if args.output:
+        save_inspection(args.output, result)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

context_engine/service/integrations.py

@@ -0,0 +1,28 @@
+"""Trusted SDK composition examples. Obtain Principal through Authenticator, not user JSON."""
+
+from ..models import Scope
+from .control import opaque
+
+
+def prepare_for_caller(memory, principal, tenant, session, question, budget, *, system):
+    """Return context for caller-managed inference; export revocation remains caller-owned."""
+    principal.authorize(tenant, session)
+    return memory.assemble(Scope(principal.tenant, session), question, budget, system=system)
+
+
+async def complete_with_groq(
+    memory, principal, tenant, session, question, budget, *, system, client
+):
+    """Use an explicit provider client; never load credentials or authorize spending."""
+    from ..providers.memory import MemoryProvider
+
+    principal.authorize(tenant, session)
+    return await MemoryProvider(memory, client, replay=False).complete(
+        Scope(principal.tenant, session),
+        question,
+        budget,
+        system=system,
+        security_scope=opaque(
+            str((principal.subject, principal.tenant, principal.role, principal.sessions))
+        ),
+    )

context_engine/service/schemas.py

@@ -0,0 +1,59 @@
+"""Strict version-1 wire input contracts; tenant, system policy and pin origin are server-owned."""
+
+from typing import Annotated, Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field
+
+Identifier = Annotated[str, Field(pattern=r"^[A-Za-z0-9_-]{1,80}$")]
+
+
+class WireModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+
+class ToolCallInput(WireModel):
+    call_id: Identifier
+    name: Identifier
+    arguments_json: Annotated[str, Field(max_length=16000)]
+
+
+class MessageInput(WireModel):
+    id: Identifier
+    role: Literal["user", "assistant", "tool"]
+    content: Annotated[str, Field(max_length=64000)]
+    tool_call_id: Identifier | None = None
+    tool_calls: Annotated[list[ToolCallInput], Field(max_length=16)] = Field(default_factory=list)
+
+
+class TurnInput(WireModel):
+    id: Identifier
+    operation_id: Identifier
+    expected_revision: Annotated[int, Field(ge=0)]
+    revision: Annotated[int, Field(ge=1)] = 1
+    timestamp: Annotated[AwareDatetime, Field(strict=False)]
+    expires_at: Annotated[AwareDatetime | None, Field(strict=False)] = None
+    messages: Annotated[list[MessageInput], Field(min_length=1, max_length=32)]
+
+
+class SourceInput(WireModel):
+    turn_id: Identifier
+    message_id: Identifier
+    revision: Annotated[int, Field(ge=1)]
+    start: Annotated[int, Field(ge=0)]
+    end: Annotated[int, Field(ge=1)]
+    message_hash: Annotated[str, Field(pattern=r"^[a-f0-9]{64}$")]
+
+
+class PinInput(WireModel):
+    value: Annotated[str, Field(min_length=1, max_length=16000)]
+    expected_revision: Annotated[int, Field(ge=0)]
+    revision: Annotated[int, Field(ge=1)] = 1
+    effective_at: Annotated[AwareDatetime, Field(strict=False)]
+    expires_at: Annotated[AwareDatetime | None, Field(strict=False)] = None
+    source: SourceInput | None = None
+
+
+class ContextInput(WireModel):
+    question: Annotated[str, Field(min_length=1, max_length=16000)]
+    expected_revision: Annotated[int, Field(ge=0)]
+    input_cap: Annotated[int, Field(ge=1, le=32000)] = 900

context_engine/service/worker.py

@@ -0,0 +1,59 @@
+"""Private stdin/stdout assembly worker; no HTTP, auth, provider or secret loading."""
+
+import sys
+import time
+
+from ..config import BudgetConfig
+from ..errors import ContextEngineError, MemoryConflict
+from ..memory import MemoryStore
+from ..memory.codec import decode, encode
+from ..models import Scope
+from ..work import DeadlineCancellation
+
+
+def execute(job):
+    memory = MemoryStore(job["memory_path"], deletion_path=job["deletion_path"])
+    scope = Scope(**job["scope"])
+    before = memory.snapshot(scope)
+    if before.revision != job["expected_revision"]:
+        raise MemoryConflict("Assembly snapshot changed")
+    snapshot, result = memory.assemble(
+        scope,
+        job["question"],
+        BudgetConfig(input_cap=job["input_cap"]),
+        system=job["system"],
+        cancellation=DeadlineCancellation(time.monotonic() + job["timeout"]),
+    )
+    if snapshot.snapshot_id != before.snapshot_id:
+        raise MemoryConflict("Assembly snapshot changed")
+    memory.assert_current(snapshot)
+    return {
+        "snapshot_id": snapshot.snapshot_id,
+        "revision": snapshot.revision,
+        "request": result.request.to_wire(),
+        "estimated_tokens": result.diagnostics.estimate.estimated_tokens,
+        "provider_accounting_verified": False,
+    }
+
+
+def main():
+    try:
+        job = decode(sys.stdin.buffer.read(262145).decode("utf-8"), maximum=262144)
+        response = {"result": execute(job)}
+    except ContextEngineError as exc:
+        status = 409 if isinstance(exc, MemoryConflict) else 422
+        if exc.code in (
+            "runtime_storage_error",
+            "memory_integrity_error",
+            "tokenizer_unavailable",
+            "work_cancelled",
+        ):
+            status = 503
+        response = {"error": exc.code, "status": status}
+    except Exception:
+        response = {"error": "assembly_worker_failed", "status": 503}
+    sys.stdout.write(encode(response))
+
+
+if __name__ == "__main__":
+    main()

context_engine/service/workers.py

@@ -0,0 +1,156 @@
+"""Bounded, disposable assembly subprocesses; no thread-cancellation illusion."""
+
+import asyncio
+import os
+import sys
+import threading
+
+from ..errors import WorkCancelled
+from ..memory.codec import decode, encode
+from .auth import AccessError
+
+MAX_OUTPUT = 2_000_000
+
+
+def worker_command():
+    return (sys.executable, "-I", "-m", "context_engine.service.worker")
+
+
+class AssemblyWorkers:
+    """Per-service-process capacity; no pending queue and no reusable tenant worker."""
+
+    def __init__(self, capacity=2):
+        self._slots = threading.BoundedSemaphore(capacity)
+        self._processes = set()
+        self._running = set()
+        self._closed = False
+
+    async def close(self):
+        self._closed = True
+        tasks = tuple(self._running)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def _exchange(self, process, payload):
+        async def write():
+            process.stdin.write(payload)
+            await process.stdin.drain()
+            process.stdin.close()
+            await process.stdin.wait_closed()
+
+        writer = asyncio.create_task(write())
+        try:
+            result = bytearray()
+            while chunk := await process.stdout.read(65536):
+                result.extend(chunk)
+                if len(result) > MAX_OUTPUT:
+                    raise AccessError(503, "assembly_output_limit")
+            await writer
+            await process.wait()
+            if process.returncode != 0:
+                raise AccessError(503, "assembly_worker_failed")
+            return decode(result.decode("utf-8"), maximum=MAX_OUTPUT)
+        finally:
+            writer.cancel()
+            await asyncio.gather(writer, return_exceptions=True)
+
+    async def run(self, job, *, timeout, receive):
+        if self._closed or not self._slots.acquire(blocking=False):
+            raise AccessError(503, "assembly_busy")
+        owner = asyncio.current_task()
+        self._running.add(owner)
+        process = None
+        spawn = None
+        tasks = []
+
+        async def disconnected():
+            while True:
+                if (await receive())["type"] == "http.disconnect":
+                    raise WorkCancelled("Client disconnected")
+
+        async def cleanup():
+            nonlocal process
+            try:
+                if process is None and spawn is not None:
+                    # create_subprocess_exec may finish after its caller is cancelled.
+                    process = await spawn
+                    self._processes.add(process)
+                for task in tasks:
+                    task.cancel()
+                if process is not None and process.returncode is None:
+                    try:
+                        process.kill()
+                    except ProcessLookupError:
+                        pass
+                await asyncio.gather(*tasks, return_exceptions=True)
+                if process is not None:
+                    # A killed writer can leave stdout paused at its high-water
+                    # mark. Discard buffered bytes so pipe closure cannot block wait().
+                    while await process.stdout.read(65536):
+                        pass
+                    await process.wait()  # Reap before capacity can be reused.
+            finally:
+                if process is None or process.returncode is not None:
+                    self._processes.discard(process)
+                    self._slots.release()
+                    self._running.discard(owner)
+
+        try:
+            payload = encode(job).encode()
+            if len(payload) > 262144:
+                raise AccessError(503, "assembly_input_limit")
+            async with asyncio.timeout(timeout):
+                # Never inherit API keys/service credentials into the computation worker.
+                env = {
+                    k: v
+                    for k, v in os.environ.items()
+                    if k
+                    in (
+                        "PATH",
+                        "SYSTEMROOT",
+                        "SystemRoot",
+                        "TMPDIR",
+                        "TEMP",
+                        "TMP",
+                        "TIKTOKEN_CACHE_DIR",
+                    )
+                }
+                spawn = asyncio.create_task(
+                    asyncio.create_subprocess_exec(
+                        *worker_command(),
+                        stdin=asyncio.subprocess.PIPE,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.DEVNULL,
+                        env=env,
+                    )
+                )
+                process = await asyncio.shield(spawn)
+                self._processes.add(process)
+                if self._closed:
+                    raise WorkCancelled("Service is shutting down")
+                exchange = asyncio.create_task(self._exchange(process, payload))
+                monitor = asyncio.create_task(disconnected())
+                tasks = [exchange, monitor]
+                done, _ = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+                if monitor in done:
+                    await monitor
+                response = await exchange
+                if set(response) == {"error", "status"}:
+                    if response["status"] not in (409, 422, 503):
+                        raise AccessError(503, "assembly_worker_failed")
+                    raise AccessError(response["status"], response["error"])
+                if set(response) != {"result"} or not isinstance(response["result"], dict):
+                    raise AccessError(503, "assembly_worker_failed")
+                return response["result"]
+        except TimeoutError:
+            raise WorkCancelled("Assembly deadline exceeded") from None
+        except (OSError, UnicodeError, BrokenPipeError):
+            raise AccessError(503, "assembly_worker_failed") from None
+        finally:
+            reaper = asyncio.create_task(cleanup())
+            try:
+                await asyncio.shield(reaper)
+            except asyncio.CancelledError:
+                await asyncio.shield(reaper)
+                raise