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

context_engine/__init__.py

@@ -0,0 +1,15 @@
+"""Core contracts. Importing this package performs no configuration or network I/O."""
+
+__version__ = "0.12.0"
+
+
+def __getattr__(name):
+    """Expose the real typed API lazily, without loading tokenizers on package import."""
+    if name in ("assemble_context", "AssembledContext", "AssemblyOptions"):
+        from . import pipeline
+
+        return getattr(pipeline, name)
+    raise AttributeError(name)
+
+
+__all__ = ["assemble_context", "AssembledContext", "AssemblyOptions", "__version__"]

context_engine/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

context_engine/_sqlite.py

@@ -0,0 +1,19 @@
+"""SQLite connection policy shared by local stores, without provider dependencies."""
+
+import os
+import sqlite3
+
+
+def connect(*args, **kwargs):
+    db = sqlite3.connect(*args, **kwargs)
+    try:
+        if os.name == "nt":
+            # Sort/index temporary data must not spill into an unchecked OS temp
+            # directory. Durable rollback/WAL files still use the private DB dir.
+            db.execute("PRAGMA temp_store=MEMORY")
+            if db.execute("PRAGMA temp_store").fetchone()[0] != 2:
+                raise sqlite3.OperationalError("Private SQLite temporary storage unavailable")
+        return db
+    except BaseException:
+        db.close()
+        raise

context_engine/_windows_security.py

@@ -0,0 +1,125 @@
+"""Fail-closed Windows credential reads; never change an operator's ACL.
+
+Parent directories and local administrators are trusted, as on POSIX. Only the
+effective user, LocalSystem and built-in Administrators may own the file or have
+applicable allow ACEs. Complex/unknown ACE forms are rejected, not approximated.
+Native imports are lazy so this module is harmless on non-Windows platforms.
+"""
+
+from pathlib import Path
+
+from .errors import ContractError
+
+TRUSTED_SYSTEM_SIDS = frozenset({"S-1-5-18", "S-1-5-32-544"})
+
+
+def check_acl(owner, user, entries):
+    """Evaluate normalized (type, flags, mask, SID) ACEs, including inherited ACEs."""
+    trusted = TRUSTED_SYSTEM_SIDS | {user}
+    if not user or owner not in trusted or entries is None:
+        raise ContractError("Configuration must have a private Windows ACL")
+    for kind, flags, mask, sid in entries:
+        if flags & 0x08:  # INHERIT_ONLY_ACE does not apply to the file itself.
+            continue
+        if kind not in (0, 1):  # Standard allow/deny only; fail closed on complex ACEs.
+            raise ContractError("Unsupported Windows configuration ACL")
+        # A deny ACE never excuses a broad allow. This intentionally conservative
+        # policy avoids pretending to implement Windows' effective-access algorithm.
+        if kind == 0 and mask and sid not in trusted:
+            raise ContractError("Configuration must have a private Windows ACL")
+
+
+class WindowsReader:
+    def __init__(self):
+        import pywintypes
+        import win32api
+        import win32con
+        import win32file
+        import win32security
+
+        self.error = pywintypes.error
+        self.api, self.con = win32api, win32con
+        self.file, self.security = win32file, win32security
+
+    def local_path(self, path):
+        path = Path(path).absolute()
+        # Exclude device/UNC namespaces, alternate streams and remote drives before
+        # CreateFile can open a pipe/device or initiate a remote connection.
+        if (
+            len(path.drive) != 2
+            or path.drive[1] != ":"
+            or not path.drive[0].isascii()
+            or not path.drive[0].isalpha()
+            or path.is_reserved()
+            or any(
+                any(char in part for char in ':<>"|?*') or part.endswith((".", " "))
+                for part in path.parts[1:]
+            )
+            or self.file.GetDriveType(path.anchor) != 3  # DRIVE_FIXED
+        ):
+            raise ContractError("Configuration requires a local disk file")
+        return path
+
+    def open(self, path):
+        c = self.con
+        path = self.local_path(path)
+        return self.file.CreateFile(
+            str(path),
+            c.GENERIC_READ | c.READ_CONTROL,
+            c.FILE_SHARE_READ,  # No concurrent writer or delete/rename handle.
+            None,  # Non-inheritable handle; no ACL mutation.
+            c.OPEN_EXISTING,
+            self.file.FILE_FLAG_OPEN_REPARSE_POINT | c.FILE_FLAG_BACKUP_SEMANTICS,
+            None,
+        )
+
+    def user(self):
+        s, c = self.security, self.con
+        try:
+            token = s.OpenThreadToken(self.api.GetCurrentThread(), c.TOKEN_QUERY, True)
+        except self.error as exc:
+            if exc.winerror != 1008:  # ERROR_NO_TOKEN only; other errors fail closed.
+                raise
+            token = s.OpenProcessToken(self.api.GetCurrentProcess(), c.TOKEN_QUERY)
+        try:
+            return s.ConvertSidToStringSid(s.GetTokenInformation(token, s.TokenUser)[0])
+        finally:
+            token.Close()
+
+    def validate(self, handle, *, directory=False):
+        # Validate the opened object, not a path that can be replaced before reading.
+        attributes = self.file.GetFileInformationByHandle(handle)[0]
+        if (
+            self.file.GetFileType(handle) != 1
+            or attributes & 0x400
+            or bool(attributes & 0x10) != directory
+        ):
+            raise ContractError("Configuration must be a regular non-reparse file")
+        s = self.security
+        sd = s.GetSecurityInfo(
+            handle, s.SE_FILE_OBJECT, s.OWNER_SECURITY_INFORMATION | s.DACL_SECURITY_INFORMATION
+        )
+        owner = s.ConvertSidToStringSid(sd.GetSecurityDescriptorOwner())
+        acl = sd.GetSecurityDescriptorDacl()
+        entries = None
+        if acl is not None:
+            entries = []
+            for index in range(acl.GetAceCount()):
+                ace = acl.GetAce(index)
+                kind, flags = ace[0]
+                # Object/callback ACE layouts differ; do not misinterpret their SID.
+                sid = s.ConvertSidToStringSid(ace[2]) if kind in (0, 1) else None
+                entries.append((kind, flags, ace[1], sid))
+        user = self.user()
+        check_acl(owner, user, entries)
+        if directory:
+            # Include inherit-only grants: SQLite-created journals inherit them.
+            check_acl(owner, user, [(k, f & ~0x08, m, s) for k, f, m, s in entries])
+            if not any(
+                k == 0 and f & 0x01 and s == user and m & 0x1F01FF == 0x1F01FF
+                for k, f, m, s in entries
+            ):
+                raise ContractError("Storage directory requires private file inheritance")
+
+    def read(self, handle, size):
+        return self.file.ReadFile(handle, size)[1]

context_engine/_windows_storage.py

@@ -0,0 +1,110 @@
+"""Private local SQLite files and inheritable directory ACLs on Windows.
+
+SQLite reopens paths, so ancestors, the effective user, SYSTEM and administrators
+must be trusted. This is not a sandbox against those principals. Existing ACLs
+are never rewritten. All native imports are lazy; no unchecked fallback exists.
+"""
+
+from glob import escape
+
+from ._windows_security import TRUSTED_SYSTEM_SIDS, WindowsReader
+from .errors import StorageError
+
+
+class WindowsStorage(WindowsReader):
+    def attributes(self):
+        import pywintypes
+
+        s = self.security
+        acl = s.ACL()
+        for sid in sorted(TRUSTED_SYSTEM_SIDS | {self.user()}):
+            acl.AddAccessAllowedAceEx(
+                s.ACL_REVISION, 0x01 | 0x02, 0x1F01FF, s.ConvertStringSidToSid(sid)
+            )
+        sd = s.SECURITY_DESCRIPTOR()
+        sd.SetSecurityDescriptorDacl(True, acl, False)
+        sd.SetSecurityDescriptorOwner(s.ConvertStringSidToSid(self.user()), False)
+        sd.SetSecurityDescriptorControl(s.SE_DACL_PROTECTED, s.SE_DACL_PROTECTED)
+        attributes = pywintypes.SECURITY_ATTRIBUTES()
+        attributes.SECURITY_DESCRIPTOR = sd
+        attributes.bInheritHandle = False
+        return attributes
+
+    def open_storage(self, path, *, create=False, exclusive=False):
+        c = self.con
+
+        def open_with(disposition, attributes):
+            return self.file.CreateFile(
+                str(path),
+                c.READ_CONTROL,
+                c.FILE_SHARE_READ | c.FILE_SHARE_WRITE | c.FILE_SHARE_DELETE,
+                attributes,
+                disposition,
+                self.file.FILE_FLAG_OPEN_REPARSE_POINT | c.FILE_FLAG_BACKUP_SEMANTICS,
+                None,
+            )
+
+        if create:
+            try:
+                return open_with(c.CREATE_NEW, self.attributes())
+            except self.error as exc:
+                if exclusive or exc.winerror not in (80, 183):
+                    raise
+        return open_with(c.OPEN_EXISTING, None)
+
+    def directory(self, path, *, create):
+        try:
+            handle = self.open_storage(path)
+        except self.error as exc:
+            if not create or exc.winerror not in (2, 3) or path == path.parent:
+                raise
+            # Only missing directories get new ACLs. Ancestors remain trusted.
+            self.make_directory(path)
+            handle = self.open_storage(path)
+        try:
+            self.validate(handle, directory=True)
+        finally:
+            handle.Close()
+
+    def make_directory(self, path):
+        # Security is applied at creation, never via a later permission rewrite.
+        if not path.parent.exists():
+            self.make_directory(path.parent)
+        try:
+            self.file.CreateDirectory(str(path), self.attributes())
+        except self.error as exc:
+            if exc.winerror != 183:  # Concurrent creator: validate below.
+                raise
+
+    def file_boundary(self, path, *, create=False, exclusive=False, optional=False):
+        try:
+            handle = self.open_storage(path, create=create, exclusive=exclusive)
+        except self.error as exc:
+            if optional and exc.winerror == 2:
+                return
+            raise
+        try:
+            self.validate(handle)
+            if self.file.GetFileInformationByHandle(handle)[7] != 1:
+                raise StorageError("Private storage cannot have hard-link aliases")
+        finally:
+            handle.Close()
+
+
+def private_file(path, *, create=False, exclusive=False):
+    """Validate the DB, parent inheritance and any existing SQLite sidecars."""
+    try:
+        boundary = WindowsStorage()
+        path = boundary.local_path(path)
+        boundary.directory(path.parent, create=create)
+        boundary.file_boundary(path, create=create, exclusive=exclusive)
+        for suffix in ("-journal", "-wal", "-shm"):
+            boundary.file_boundary(path.with_name(path.name + suffix), optional=True)
+        # Multi-database DELETE transactions can leave super-journals.
+        for sidecar in path.parent.glob(escape(path.name) + "-mj*"):
+            boundary.file_boundary(sidecar, optional=True)
+        return path
+    except Exception:
+        raise StorageError(
+            "Storage requires private local Windows files and directory ACLs"
+        ) from None

context_engine/adapters.py

@@ -0,0 +1,148 @@
+"""Provider and framework message adapters. Optional; no provider SDK is imported.
+
+Assembly output is one system message, user data blocks and the user question, plus
+optional tool schemas. These helpers reshape it for common clients:
+
+    client.chat.completions.create(model=..., **openai_chat(result))
+    client.messages.create(model=..., max_tokens=..., **anthropic_messages(result))
+    chat_model.invoke(langchain_messages(result))   # needs the [langchain] extra
+
+`turns_from_openai` goes the other way: it converts an existing OpenAI-style chat
+history into `Turn`s for `assemble_context` or `MemoryStore`.
+"""
+
+import json
+from collections.abc import Iterable, Mapping
+from datetime import UTC, datetime
+
+from .errors import ContractError
+from .models import ChatRequest, Message, Role, Scope, ToolCall, Turn
+
+
+def _request(result) -> ChatRequest:
+    request = getattr(result, "request", result)
+    if not isinstance(request, ChatRequest):
+        raise ContractError("Expected an AssembledContext or ChatRequest")
+    return request
+
+
+def openai_chat(result) -> dict:
+    """`messages` (and `tools`, when present) for OpenAI-compatible chat APIs."""
+    return _request(result).to_wire()
+
+
+def anthropic_messages(result) -> dict:
+    """`system`, `messages` (and `tools`) for the Anthropic Messages API.
+
+    The system prompt becomes the top-level `system` field; consecutive user data
+    blocks are merged into one user turn of text blocks, as the API expects.
+    """
+    request = _request(result)
+    system, messages = [], []
+    for message in request.messages:
+        if message.role == Role.SYSTEM:
+            system.append(message.content)
+        elif message.role == Role.USER and not message.tool_calls:
+            block = {"type": "text", "text": message.content}
+            if messages and messages[-1]["role"] == "user":
+                messages[-1]["content"].append(block)
+            else:
+                messages.append({"role": "user", "content": [block]})
+        else:
+            raise ContractError("Anthropic adapter supports assembled system/user messages only")
+    payload: dict = {"system": "\n\n".join(system), "messages": messages}
+    if request.tools:
+        payload["tools"] = [
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "input_schema": json.loads(tool.parameters_json),
+            }
+            for tool in request.tools
+        ]
+    return payload
+
+
+def langchain_messages(result) -> list:
+    """LangChain `SystemMessage`/`HumanMessage` objects; needs `langchain-core`."""
+    try:
+        from langchain_core.messages import HumanMessage, SystemMessage
+    except ImportError:
+        raise ImportError(
+            "langchain_messages needs langchain-core: "
+            "pip install 'context-engineering-core[langchain]'"
+        ) from None
+    converted = []
+    for message in _request(result).messages:
+        if message.role == Role.SYSTEM:
+            converted.append(SystemMessage(content=message.content))
+        elif message.role == Role.USER and not message.tool_calls:
+            converted.append(HumanMessage(content=message.content))
+        else:
+            raise ContractError("LangChain adapter supports assembled system/user messages only")
+    return converted
+
+
+def _text(content, index: int) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list) and all(
+        isinstance(part, Mapping) and part.get("type") == "text" for part in content
+    ):
+        return "".join(str(part.get("text", "")) for part in content)
+    raise ContractError("Only text message content is supported", field=f"messages[{index}]")
+
+
+def turns_from_openai(
+    messages: Iterable[Mapping],
+    scope: Scope,
+    *,
+    id_prefix: str = "",
+    timestamp: datetime | None = None,
+) -> tuple[Turn, ...]:
+    """Group an OpenAI-style history into turns: each user message starts a new turn.
+
+    IDs come from positions (`{id_prefix}t{n}` / `{id_prefix}m{i}`), so converting
+    the same history twice yields the same IDs and provenance. Pass the system prompt
+    to `assemble_context(system=...)` instead of including it here.
+    """
+    if not isinstance(scope, Scope):
+        raise ContractError("turns_from_openai requires a Scope")
+    at = timestamp or datetime.now(UTC)
+    groups: list[list[Message]] = []
+    for index, item in enumerate(messages):
+        if not isinstance(item, Mapping):
+            raise ContractError("Each message must be a mapping", field=f"messages[{index}]")
+        role = item.get("role")
+        if role == "system" or role == "developer":
+            raise ContractError(
+                "Pass system instructions via system=, not history", field=f"messages[{index}]"
+            )
+        if role not in ("user", "assistant", "tool"):
+            raise ContractError("Unsupported message role", field=f"messages[{index}]")
+        try:
+            calls = tuple(
+                ToolCall(call["id"], call["function"]["name"], call["function"]["arguments"])
+                for call in item.get("tool_calls") or ()
+            )
+        except (KeyError, TypeError):
+            raise ContractError("Malformed tool call", field=f"messages[{index}]") from None
+        message = Message(
+            f"{id_prefix}m{index}",
+            Role(role),
+            _text(item.get("content"), index),
+            tool_call_id=item.get("tool_call_id"),
+            tool_calls=calls,
+        )
+        if role == "user" or not groups:
+            groups.append([])
+        groups[-1].append(message)
+    return tuple(
+        Turn(f"{id_prefix}t{number}", scope, tuple(group), timestamp=at)
+        for number, group in enumerate(groups)
+    )
+
+
+__all__ = ["anthropic_messages", "langchain_messages", "openai_chat", "turns_from_openai"]

context_engine/answers.py

@@ -0,0 +1,90 @@
+"""Opt-in exact JSON answer conformance; never truth grading or inference."""
+
+import json
+import re
+import unicodedata
+from dataclasses import dataclass
+
+from .errors import ContractError
+
+MAX_DOCUMENT_BYTES = 16384
+PATTERNS = {
+    "ascii_identifier": r"[A-Za-z0-9][A-Za-z0-9._:/-]*",
+    "integer": r"(?:0|-?[1-9][0-9]*|UNKNOWN)",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class AnswerContract:
+    """Strict value preservation. The caller owns evidence and authorization checks."""
+
+    kind: str = "text"
+    max_characters: int = 512
+
+    def __post_init__(self):
+        if self.kind not in ("text", "ascii_identifier", "integer"):
+            raise ContractError("Unsupported answer kind")
+        if type(self.max_characters) is not int or not 7 <= self.max_characters <= 2048:
+            raise ContractError("Answer length limit must be between7 and2048")
+
+    def json_schema(self) -> dict:
+        value = {"type": "string", "minLength": 1, "maxLength": self.max_characters}
+        if self.kind in PATTERNS:
+            value["pattern"] = "^(?:" + PATTERNS[self.kind] + ")$"
+        return {
+            "type": "object",
+            "additionalProperties": False,
+            "required": ["answer"],
+            "properties": {"answer": value},
+        }
+
+    def instructions(self) -> str:
+        constraint = {
+            "text": "Preserve the exact value, including case and Unicode characters.",
+            "ascii_identifier": "Use an exact ASCII identifier; never replace its hyphens or case.",
+            "integer": "Use a base-ten integer string without plus signs or leading zeros.",
+        }[self.kind]
+        return (
+            'Return only one JSON object with exactly one string field named "answer". '
+            'If evidence is missing or unresolved, return {"answer":"UNKNOWN"}. '
+            "Do not include Markdown, explanations, extra fields, or surrounding value whitespace. "
+            "The value must be a single line with no control characters. "
+            f"Maximum value length: {self.max_characters} characters. " + constraint
+        )
+
+    def parse(self, document: str) -> str:
+        """Reject, never repair/extract/normalize. Sanitized errors omit response bodies."""
+        try:
+            if not isinstance(document, str) or len(document) > MAX_DOCUMENT_BYTES:
+                raise ValueError
+            if len(document.encode("utf-8")) > MAX_DOCUMENT_BYTES:
+                raise ValueError
+
+            def pairs(items):
+                result = {}
+                for key, value in items:
+                    if key in result:
+                        raise ValueError
+                    result[key] = value
+                return result
+
+            def invalid_constant(_value):
+                raise ValueError
+
+            value = json.loads(document, object_pairs_hook=pairs, parse_constant=invalid_constant)
+            if not isinstance(value, dict) or set(value) != {"answer"}:
+                raise ValueError
+            answer = value["answer"]
+            if (
+                not isinstance(answer, str)
+                or not 1 <= len(answer) <= self.max_characters
+                or answer != answer.strip()
+                or any(unicodedata.category(c) in {"Cc", "Cs", "Zl", "Zp"} for c in answer)
+            ):
+                raise ValueError
+            answer.encode("utf-8")
+            if self.kind in PATTERNS and not re.fullmatch(PATTERNS[self.kind], answer):
+                raise ValueError
+            return answer
+        except (ValueError, TypeError, UnicodeError, RecursionError):
+            raise ContractError("Answer does not conform to the exact JSON contract") from None

context_engine/budget.py

@@ -0,0 +1,93 @@
+"""Mandatory budget reservation and complete serialized-request admission."""
+
+from dataclasses import dataclass
+
+from .config import BudgetConfig
+from .errors import ContractError, LayerAllocationError, PromptTooLarge, RequiredContextTooLarge
+from .models import ChatRequest, freeze_sequence, integer_value
+from .tokens import TokenCounter, TokenEstimate
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetPlan:
+    input_allowance: int
+    required_estimate: TokenEstimate
+    retrieval_tokens: int
+    summary_tokens: int
+    window_tokens: int
+    window_turn_ids: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        integer_value("input_allowance", self.input_allowance, minimum=1)
+        if not isinstance(self.required_estimate, TokenEstimate):
+            raise ContractError("Budget plan requires a token estimate")
+        for name in ("retrieval_tokens", "summary_tokens", "window_tokens"):
+            integer_value(name, getattr(self, name))
+        ids = freeze_sequence(self, "window_turn_ids", str)
+        if len(set(ids)) != len(ids) or any(not identifier.strip() for identifier in ids):
+            raise ContractError("Window turn IDs must be unique and nonempty")
+        allocated = (
+            self.required_estimate.estimated_tokens
+            + self.retrieval_tokens
+            + self.summary_tokens
+            + self.window_tokens
+        )
+        if allocated != self.input_allowance:
+            raise ContractError("Budget allocations must equal the input allowance")
+
+    def to_dict(self) -> dict:
+        return {
+            "input_allowance": self.input_allowance,
+            "required": self.required_estimate.to_dict(),
+            "retrieval_tokens": self.retrieval_tokens,
+            "summary_tokens": self.summary_tokens,
+            "window_tokens": self.window_tokens,
+            "window_turn_ids": list(self.window_turn_ids),
+        }
+
+
+def plan_budget(
+    *, required_request: ChatRequest, config: BudgetConfig, counter: TokenCounter
+) -> BudgetPlan:
+    """Reserve a caller-supplied mandatory request without dropping any content.
+
+    The assembly layer must supply system, active pins, question and tool schemas.
+    Layer allocations use calibrated token units and include incremental framing;
+    they are not raw text-token limits. Assembly recounts the final whole request.
+    """
+    estimate = counter.count_request(required_request)
+    allowance = config.input_allowance
+    remaining = allowance - estimate.estimated_tokens
+    if remaining < 0:
+        raise RequiredContextTooLarge(
+            "Required context exceeds the input allowance; "
+            "reduce supplied content or raise the budget",
+            required_tokens=estimate.estimated_tokens,
+            input_allowance=allowance,
+            overflow_tokens=-remaining,
+        )
+    reserve = config.retrieval_reserve + config.summary_reserve
+    if reserve > remaining:
+        raise LayerAllocationError(
+            "Layer reserves exceed space remaining after required context",
+            available_tokens=remaining,
+            reserved_tokens=reserve,
+        )
+    return BudgetPlan(
+        allowance, estimate, config.retrieval_reserve, config.summary_reserve, remaining - reserve
+    )
+
+
+def validate_request(
+    *, request: ChatRequest, config: BudgetConfig, counter: TokenCounter
+) -> TokenEstimate:
+    """Recount an entire final request. Never infer safety from per-block sums."""
+    estimate = counter.count_request(request)
+    if estimate.estimated_tokens > config.input_allowance:
+        raise PromptTooLarge(
+            "Serialized request exceeds the estimated input allowance",
+            estimated_tokens=estimate.estimated_tokens,
+            input_allowance=config.input_allowance,
+            overflow_tokens=estimate.estimated_tokens - config.input_allowance,
+        )
+    return estimate