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

context_engine/providers/commands.py

@@ -0,0 +1,138 @@
+"""Explicit live probe and an entirely synthetic accounting demonstration."""
+
+import asyncio
+import os
+from dataclasses import replace
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from ..config import BudgetConfig, Settings
+from ..errors import ContractError
+from ..inspection import demo_job, load_job
+from ..models import ChatRequest, Message, Role, Scope
+from ..tokens import TiktokenCounter
+from .client import ProviderClient
+from .contracts import Completion, GenerationConfig, PriceCard, QuotaPolicy, ReplayPolicy, Usage
+from .store import RuntimeStore
+
+
+class SyntheticTransport:
+    namespace = "c05-offline-demo-v1"
+
+    def __init__(self):
+        self.calls = 0
+
+    async def send(self, payload, api_key, timeout):
+        self.calls += 1
+        return Completion(
+            payload["model"],
+            f"synthetic-{self.calls}",
+            "synthetic-answer",
+            "stop",
+            Usage(40, 5, cached_input_tokens=4, reasoning_tokens=2),
+        )
+
+
+async def _demo(directory: Path) -> dict:
+    store = RuntimeStore(directory / "runtime.sqlite")
+    quota = QuotaPolicy("synthetic-demo", 10000, rpd=2)
+    transport = SyntheticTransport()
+    client = ProviderClient(
+        store=store,
+        quota=quota,
+        prices=PriceCard("synthetic-v1", 1000000, 500000, 2000000),
+        transport=transport,
+        api_key="synthetic-not-a-credential",
+        replay=ReplayPolicy(enabled=True),
+    )
+    request = ChatRequest((Message("q", Role.USER, "Synthetic question one?"),))
+    options = dict(
+        scope=Scope("demo", "demo"), security_scope="synthetic-v1", snapshot_revision="synthetic-v1"
+    )
+    budget = BudgetConfig(input_cap=900)
+    first = await client.complete(request, budget, **options)
+    replay = await client.complete(request, budget, **options)
+    changed = ChatRequest((Message("q", Role.USER, "Synthetic question two?"),))
+    miss = await client.complete(changed, budget, **options)
+    client.generation = replace(client.generation, temperature=0.5)
+    blocked = await client.complete(changed, budget, **options)
+    results = dict(
+        first=first.to_dict(),
+        identical_replay=replay.to_dict(),
+        changed_question=miss.to_dict(),
+        changed_generation=blocked.to_dict(),
+    )
+    valid = (
+        first.status == miss.status == "success"
+        and replay.status == "replay"
+        and replay.new_cost_microusd == 0
+        and blocked.error_code == "quota_exhausted"
+        and blocked.request_key != miss.request_key
+        and transport.calls == 2
+    )
+    return dict(
+        mode="offline_provider_demo",
+        status="PASS" if valid else "FAIL",
+        real_inference_calls=0,
+        simulated_transport_calls=transport.calls,
+        pricing="synthetic; not provider pricing or billing evidence",
+        results=results,
+        ledger=store.snapshot(quota),
+    )
+
+
+def provider_demo() -> dict:
+    with TemporaryDirectory(prefix="context-provider-demo-") as directory:
+        # Let the store create its private directory, not tempfile's Windows ACL.
+        return asyncio.run(_demo(Path(directory) / "storage"))
+
+
+def provider_probe(args) -> dict:
+    # All authorization/config checks precede the first file mutation or network operation.
+    if not args.allow_live or args.daily_budget_microusd <= 0:
+        raise ContractError("Live probe requires --allow-live and a positive explicit spending cap")
+    api_key = os.environ.get("GROQ_API_KEY")
+    if not api_key or any(ord(c) < 33 or ord(c) > 126 for c in api_key):
+        raise ContractError("Live probe requires a valid GROQ_API_KEY environment variable")
+    quota = QuotaPolicy(
+        args.account_id,
+        args.daily_budget_microusd,
+        rpm=args.rpm,
+        tpm=args.tpm,
+        rpd=args.rpd,
+        tpd=args.tpd,
+    )
+    prices = PriceCard(
+        args.price_version,
+        args.input_rate_microusd,
+        args.cached_input_rate_microusd,
+        args.output_rate_microusd,
+    )
+    settings = Settings.from_env()
+    job = load_job(args.input, settings) if args.input is not None else demo_job(settings)
+    generation = GenerationConfig(
+        model=args.model, max_completion_tokens=job.arguments["budget"].completion_reservation
+    )
+    assembled = job.run()
+    client = ProviderClient(
+        store=RuntimeStore(args.ledger),
+        quota=quota,
+        prices=prices,
+        api_key=api_key,
+        generation=generation,
+        counter=TiktokenCounter(job.tokenizer),
+    )
+    result = asyncio.run(
+        client.complete(
+            assembled.request,
+            job.arguments["budget"],
+            scope=job.arguments["pinned_facts"].scope,
+            security_scope=args.security_scope,
+            snapshot_revision=args.snapshot_revision,
+        )
+    )
+    return dict(
+        mode="live_provider_probe",
+        synthetic_input=job.synthetic,
+        **result.to_dict(include_content=args.show_content),
+    )

context_engine/providers/contracts.py

@@ -0,0 +1,324 @@
+"""Provider/accounting contracts; monetary amounts are integer micro-US dollars."""
+
+import hashlib
+import math
+import re
+from dataclasses import asdict, dataclass
+
+from ..errors import ContractError
+from ..models import ToolCall, canonical_json, freeze_sequence, integer_value, text_value
+
+ENDPOINT = "https://api.groq.com/openai/v1/chat/completions"
+ADAPTER_VERSION = "groq-chat-v1"
+MODELS = ("openai/gpt-oss-120b", "openai/gpt-oss-20b")
+# Inception Mercury (OpenAI-compatible); paid per token, no documented free tier.
+INCEPTION_ENDPOINT = "https://api.inceptionlabs.ai/v1/chat/completions"
+INCEPTION_ADAPTER_VERSION = "inception-chat-v1"
+INCEPTION_MODELS = ("mercury-3", "mercury-2.5", "mercury-2")
+
+
+def fingerprint(value) -> str:
+    return hashlib.sha256(canonical_json(value).encode()).hexdigest()
+
+
+def positive_number(name, value, maximum=300):
+    if type(value) not in (int, float) or not math.isfinite(value) or not 0 < value <= maximum:
+        raise ContractError("Expected a positive finite bounded duration", field=name)
+
+
+def identifier(value: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9._:/-]{1,200}", value):
+        raise ContractError("Invalid opaque provider identifier")
+    return value
+
+
+@dataclass(frozen=True)
+class GenerationConfig:
+    model: str = MODELS[0]
+    max_completion_tokens: int = 256
+    temperature: float = 0.0
+    reasoning_effort: str = "low"
+    tool_choice: str = "none"
+
+    def __post_init__(self):
+        if self.model not in MODELS or self.reasoning_effort not in ("low", "medium", "high"):
+            raise ContractError("Unsupported C05 model or reasoning setting")
+        integer_value("max_completion_tokens", self.max_completion_tokens, minimum=1)
+        if self.max_completion_tokens > 65536:
+            raise ContractError("Completion request exceeds model profile")
+        if (
+            type(self.temperature) not in (int, float)
+            or not math.isfinite(self.temperature)
+            or not 0 <= self.temperature <= 2
+        ):
+            raise ContractError("Invalid generation temperature")
+        if self.tool_choice not in ("none", "auto"):
+            raise ContractError("Unsupported tool choice")
+
+    def to_wire(self, request):
+        payload = {
+            **request.to_wire(),
+            **asdict(self),
+            "stream": False,
+            "n": 1,
+            "include_reasoning": False,
+            "service_tier": "on_demand",
+        }
+        if not request.tools:
+            payload.pop("tool_choice")
+        return payload
+
+
+@dataclass(frozen=True)
+class InceptionGenerationConfig:
+    """Mercury request settings; the API accepts temperature 0.5-1 only."""
+
+    model: str = "mercury-3"
+    max_completion_tokens: int = 256
+    temperature: float = 0.5
+    reasoning_effort: str = "low"
+    tool_choice: str = "none"
+
+    def __post_init__(self):
+        if self.model not in INCEPTION_MODELS or self.reasoning_effort not in (
+            "instant",
+            "low",
+            "medium",
+            "high",
+        ):
+            raise ContractError("Unsupported Inception model or reasoning setting")
+        integer_value("max_completion_tokens", self.max_completion_tokens, minimum=1)
+        if self.max_completion_tokens > 50000:
+            raise ContractError("Completion request exceeds the smallest Mercury limit")
+        if (
+            type(self.temperature) not in (int, float)
+            or not math.isfinite(self.temperature)
+            or not 0.5 <= self.temperature <= 1
+        ):
+            raise ContractError("Inception temperature must be between 0.5 and 1")
+        if self.tool_choice not in ("none", "auto"):
+            raise ContractError("Unsupported tool choice")
+
+    def to_wire(self, request):
+        payload = {**request.to_wire(), **asdict(self), "stream": False}
+        if not request.tools:
+            payload.pop("tool_choice")
+        return payload
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    max_attempts: int = 3
+    attempt_timeout: float = 20.0
+    total_timeout: float = 45.0
+    max_backoff: float = 10.0
+
+    def __post_init__(self):
+        integer_value("max_attempts", self.max_attempts, minimum=1)
+        if self.max_attempts > 5:
+            raise ContractError("Retry attempt limit is five")
+        for name in ("attempt_timeout", "total_timeout", "max_backoff"):
+            positive_number(name, getattr(self, name))
+
+
+@dataclass(frozen=True)
+class QuotaPolicy:
+    account_id: str
+    daily_budget_microusd: int = 0
+    rpm: int = 30
+    tpm: int = 8000
+    rpd: int = 1000
+    tpd: int = 200000
+    billing_mode: str = "metered"
+
+    def __post_init__(self):
+        identifier(self.account_id)
+        if self.billing_mode not in ("metered", "free_tier"):
+            raise ContractError("Billing mode must be metered or explicitly confirmed free_tier")
+        if self.billing_mode == "free_tier" and self.daily_budget_microusd != 0:
+            raise ContractError("Free-tier mode requires a zero daily paid-spending cap")
+        for name in ("daily_budget_microusd", "rpm", "tpm", "rpd", "tpd"):
+            integer_value(name, getattr(self, name))
+            if getattr(self, name) > 10**12:
+                raise ContractError("Quota exceeds local integer accounting range")
+
+    def validate_prices(self, prices):
+        if not isinstance(prices, PriceCard):
+            raise ContractError("A validated price card is required")
+        if self.billing_mode == "free_tier" and prices.reserve_cost(1_000_000, 1_000_000) != 0:
+            raise ContractError("Free-tier mode requires zero configured token prices")
+
+
+@dataclass(frozen=True)
+class PriceCard:
+    version: str
+    input_per_million_microusd: int
+    cached_input_per_million_microusd: int
+    output_per_million_microusd: int
+
+    def __post_init__(self):
+        identifier(self.version)
+        for name in (
+            "input_per_million_microusd",
+            "cached_input_per_million_microusd",
+            "output_per_million_microusd",
+        ):
+            integer_value(name, getattr(self, name))
+            if getattr(self, name) > 10**12:
+                raise ContractError("Price exceeds local integer accounting range")
+
+    def cost(self, input_tokens: int, output_tokens: int, cached_tokens: int = 0) -> int:
+        for value in (input_tokens, output_tokens, cached_tokens):
+            integer_value("tokens", value)
+        if cached_tokens > input_tokens:
+            raise ContractError("Cached input exceeds total input")
+        numerator = (
+            (input_tokens - cached_tokens) * self.input_per_million_microusd
+            + cached_tokens * self.cached_input_per_million_microusd
+            + output_tokens * self.output_per_million_microusd
+        )
+        return (numerator + 999999) // 1000000
+
+    def reserve_cost(self, input_tokens: int, output_tokens: int) -> int:
+        for value in (input_tokens, output_tokens):
+            integer_value("tokens", value)
+        # Never assume that caching is discounted in an arbitrary caller-supplied price card.
+        numerator = input_tokens * max(
+            self.input_per_million_microusd, self.cached_input_per_million_microusd
+        )
+        return (numerator + output_tokens * self.output_per_million_microusd + 999999) // 1000000
+
+    def observed_cost(self, usage) -> int:
+        if usage.cached_input_tokens is None:
+            return self.reserve_cost(usage.input_tokens, usage.output_tokens)
+        return self.cost(usage.input_tokens, usage.output_tokens, usage.cached_input_tokens)
+
+
+@dataclass(frozen=True)
+class ReplayPolicy:
+    enabled: bool = False
+    ttl_seconds: int = 3600
+
+    def __post_init__(self):
+        if type(self.enabled) is not bool:
+            raise ContractError("Replay must be explicitly enabled with a boolean")
+        integer_value("ttl_seconds", self.ttl_seconds, minimum=1)
+        if self.ttl_seconds > 86400:
+            raise ContractError("C05 replay TTL is limited to one day")
+
+
+@dataclass(frozen=True)
+class Usage:
+    input_tokens: int
+    output_tokens: int
+    cached_input_tokens: int | None = None
+    reasoning_tokens: int | None = None
+
+    def __post_init__(self):
+        for name in ("input_tokens", "output_tokens"):
+            integer_value(name, getattr(self, name))
+        for name, maximum in (
+            ("cached_input_tokens", self.input_tokens),
+            ("reasoning_tokens", self.output_tokens),
+        ):
+            value = getattr(self, name)
+            if value is not None:
+                integer_value(name, value)
+                if value > maximum:
+                    raise ContractError("Usage detail exceeds its containing total")
+        if self.input_tokens + self.output_tokens > 10**9:
+            raise ContractError("Usage exceeds supported accounting range")
+
+    @property
+    def total_tokens(self):
+        return self.input_tokens + self.output_tokens
+
+    @property
+    def visible_output_tokens(self):
+        return None if self.reasoning_tokens is None else self.output_tokens - self.reasoning_tokens
+
+
+@dataclass(frozen=True)
+class Completion:
+    model: str
+    response_id: str
+    content: str
+    finish_reason: str
+    usage: Usage
+    tool_calls: tuple[ToolCall, ...] = ()
+    system_fingerprint: str | None = None
+
+    def __post_init__(self):
+        identifier(self.response_id)
+        if self.model not in MODELS + INCEPTION_MODELS or self.finish_reason not in (
+            "stop",
+            "length",
+            "tool_calls",
+            "content_filter",
+        ):
+            raise ContractError("Unsupported provider completion")
+        text_value("content", self.content, nonempty=False)
+        if not isinstance(self.usage, Usage):
+            raise ContractError("Completion requires validated usage")
+        calls = freeze_sequence(self, "tool_calls", ToolCall)
+        if bool(calls) != (self.finish_reason == "tool_calls") or len(
+            {c.call_id for c in calls}
+        ) != len(calls):
+            raise ContractError("Tool-call finish reason disagrees with response")
+        if self.system_fingerprint is not None:
+            identifier(self.system_fingerprint)
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, value):
+        data = dict(value)
+        data["usage"] = Usage(**data["usage"])
+        data["tool_calls"] = tuple(ToolCall(**c) for c in data["tool_calls"])
+        return cls(**data)
+
+
+class TransportFailure(Exception):
+    """Only controlled metadata crosses the network/ledger boundary."""
+
+    def __init__(
+        self, code: str, *, uncertain: bool, retryable=False, retry_after=None, usage=None
+    ):
+        identifier(code)
+        if type(uncertain) is not bool or type(retryable) is not bool:
+            raise ContractError("Failure flags must be booleans")
+        if retry_after is not None and (
+            type(retry_after) not in (int, float)
+            or not math.isfinite(retry_after)
+            or retry_after < 0
+        ):
+            raise ContractError("Invalid retry delay")
+        if usage is not None and not isinstance(usage, Usage):
+            raise ContractError("Failure usage must be validated")
+        super().__init__(code)
+        self.code, self.uncertain, self.retryable = code, uncertain, retryable
+        self.retry_after, self.usage = retry_after, usage
+
+
+@dataclass(frozen=True)
+class ModelResult:
+    status: str
+    request_key: str
+    attempt_ids: tuple[str, ...] = ()
+    completion: Completion | None = None
+    error_code: str | None = None
+    replay_of: str | None = None
+    new_cost_microusd: int | None = 0
+    original_cost_microusd: int | None = None
+    warning: str | None = None
+
+    def to_dict(self, *, include_content=False):
+        if type(include_content) is not bool:
+            raise ContractError("Content export requires an explicit boolean")
+        result = asdict(self)
+        if self.completion is not None and not include_content:
+            result["completion"].pop("content")
+            result["completion"].pop("tool_calls")
+        result["content_included"] = include_content
+        return result

context_engine/providers/credentials.py

@@ -0,0 +1,66 @@
+"""Explicit, bounded credential loading; no shell evaluation or secret-bearing errors."""
+
+import os
+import stat
+from pathlib import Path
+
+from ..errors import ContractError
+
+
+def private_bytes(path, maximum):
+    if os.name == "nt":
+        from .windows_credentials import private_bytes as windows_private_bytes
+
+        return windows_private_bytes(path, maximum)
+    descriptor = None
+    try:
+        descriptor = os.open(
+            Path(path), os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+        )
+        info = os.fstat(descriptor)
+        if not stat.S_ISREG(info.st_mode) or (os.name == "posix" and info.st_mode & 0o077):
+            raise ContractError("Configuration must be a private regular file")
+        with os.fdopen(descriptor, "rb") as handle:
+            descriptor = None
+            raw = handle.read(maximum + 1)
+        if len(raw) > maximum:
+            raise ContractError("Private configuration exceeds its size limit")
+        return raw
+    except (OSError, TypeError, ValueError):
+        raise ContractError("Cannot read private configuration") from None
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def load_api_key(env_file=None):
+    key = os.environ.get("GROQ_API_KEY")
+    if env_file is not None:
+        try:
+            lines = private_bytes(env_file, 8192).decode("ascii").splitlines()
+        except UnicodeError:
+            raise ContractError("Credential file must contain a plain ASCII assignment") from None
+        values = []
+        for line in lines:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            name, sep, value = line.partition("=")
+            if sep != "=" or name.strip() != "GROQ_API_KEY":
+                raise ContractError("Credential file permits only GROQ_API_KEY and comments")
+            value = value.strip()
+            if len(value) >= 2 and value[0] in "\"'" and value[-1] == value[0]:
+                value = value[1:-1]
+            values.append(value)
+        if len(values) != 1:
+            raise ContractError("Credential file requires exactly one GROQ_API_KEY assignment")
+        if key and key != values[0]:
+            raise ContractError("Environment and explicit credential file disagree")
+        key = values[0]
+    if (
+        not key
+        or len(key) > 4096
+        or any(not (c.isascii() and (c.isalnum() or c in "_-")) for c in key)
+    ):
+        raise ContractError("Missing or invalid credential; value is never displayed")
+    return key

context_engine/providers/memory.py

@@ -0,0 +1,112 @@
+"""Optional memory-aware inference; memory owns replay lifecycle, not the provider cache."""
+
+import uuid
+from dataclasses import asdict
+
+from ..errors import ContractError, MemoryConflict, MemoryIntegrityError
+from ..memory import MemoryStore
+from .client import ProviderClient
+from .contracts import Completion, ModelResult, fingerprint
+
+
+class MemoryProvider:
+    def __init__(self, memory: MemoryStore, client: ProviderClient, *, replay=False):
+        if not isinstance(memory, MemoryStore) or not isinstance(client, ProviderClient):
+            raise ContractError("Memory integration requires validated stores/client")
+        if type(replay) is not bool or client.replay.enabled:
+            raise ContractError(
+                "Use memory-managed replay only; provider body cache must be disabled"
+            )
+        self.memory, self.client, self.replay = memory, client, replay
+
+    async def complete(self, scope, question, budget, *, system, security_scope, **assembly):
+        if not isinstance(security_scope, str) or not security_scope.strip():
+            raise ContractError("An authorized security scope is required")
+        snapshot, context = self.memory.assemble(scope, question, budget, system=system, **assembly)
+        client = self.client
+        key = fingerprint(
+            {
+                "snapshot": snapshot.snapshot_id,
+                "request": context.request.to_wire(),
+                "security": security_scope,
+                "budget": asdict(budget),
+                "generation": asdict(client.generation),
+                "prices": asdict(client.prices),
+                "account": client.quota.account_id,
+                "counting": context.diagnostics.estimate.to_dict(),
+                "transport": getattr(
+                    client.transport, "namespace", type(client.transport).__qualname__
+                ),
+                "policy": "memory-provider-v1",
+            }
+        )
+        if self.replay and (cached := self.memory.cache_get(snapshot, key)) is not None:
+            try:
+                completion = Completion.from_dict(cached["completion"])
+                with client.store.transaction() as db:
+                    source = db.execute(
+                        "SELECT * FROM attempts WHERE id=?", (cached["attempt_id"],)
+                    ).fetchone()
+                    if (
+                        source is None
+                        or source["account"] != fingerprint(client.quota.account_id)
+                        or source["state"] != "completed"
+                        or source["request_key"] != cached["request_key"]
+                        or source["completion_hash"] != fingerprint(completion.to_dict())
+                        or source["cost"] != cached["cost"]
+                    ):
+                        raise MemoryIntegrityError("Memory replay ancestry is invalid")
+                    db.execute(
+                        "INSERT INTO events(id,account,request_key,created,kind,source_attempt,"
+                        "new_cost) VALUES(?,?,?,?,?,?,0)",
+                        (
+                            uuid.uuid4().hex,
+                            source["account"],
+                            source["request_key"],
+                            client.clock(),
+                            "memory_replay",
+                            source["id"],
+                        ),
+                    )
+                self.memory.assert_current(snapshot)
+                return ModelResult(
+                    "replay",
+                    cached["request_key"],
+                    completion=completion,
+                    replay_of=cached["attempt_id"],
+                    new_cost_microusd=0,
+                    original_cost_microusd=cached["cost"],
+                )
+            except (KeyError, TypeError, ValueError):
+                raise MemoryIntegrityError("Malformed memory replay") from None
+        result = await client.complete(
+            context.request,
+            budget,
+            scope=scope,
+            security_scope=security_scope,
+            snapshot_revision=snapshot.snapshot_id,
+            policy_version="memory-provider-v1",
+        )
+        try:
+            self.memory.assert_current(snapshot)
+            if self.replay and result.status == "success":
+                self.memory.cache_put(
+                    snapshot,
+                    key,
+                    {
+                        "completion": result.completion.to_dict(),
+                        "attempt_id": result.attempt_ids[-1],
+                        "request_key": result.request_key,
+                        "cost": result.original_cost_microusd,
+                    },
+                )
+        except MemoryConflict:
+            return ModelResult(
+                "error",
+                result.request_key,
+                result.attempt_ids,
+                error_code="memory_revision_conflict",
+                new_cost_microusd=result.new_cost_microusd,
+                warning="response_discarded_memory_changed",
+            )
+        return result