proseforge-agent 0.2.0__py3-none-any.whl

proseforge_agent/__init__.py

@@ -0,0 +1,10 @@
+"""ProseForge Agent package.
+
+Importing this package must not read configuration, touch the filesystem,
+or require API keys. Subsystem behavior lives behind dedicated submodules
+that are imported explicitly by their callers.
+"""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

proseforge_agent/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m proseforge_agent`` entry point (Task 190)."""
+
+import proseforge_agent._bootstrap  # noqa: F401  # UTF-8 + path hardening, must be first
+
+from proseforge_agent.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

proseforge_agent/_bootstrap.py

@@ -0,0 +1,108 @@
+"""Early process bootstrap (Task 190).
+
+Fixes Windows text-encoding issues before any user-facing output and hardens
+the import path. Imported as the very first line of every entry point
+(``cli``, ``chat.repl``, ``demo``, ``__main__``) so a UTF-8-safe interpreter is
+guaranteed before the rest of the package loads.
+
+Four responsibilities, each guarded so the bootstrap NEVER raises:
+
+1. Force UTF-8 for child processes (``PYTHONUTF8``, ``PYTHONIOENCODING``).
+2. Reconfigure stdout/stderr/stdin to UTF-8 with ``errors="replace"``.
+3. Harden ``sys.path`` (prepend the package source root, strip ``""``/``.``).
+4. Record everything in :data:`STATE` for observability.
+
+Safe to import multiple times: a guard on ``sys._pf_agent_bootstrapped``
+makes repeat calls a no-op.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+
+STATE: dict[str, Any] = {
+    "already_installed": False,
+    "python_utf8_set": None,
+    "stdout_reconfigured": None,
+    "stderr_reconfigured": None,
+    "stdin_reconfigured": None,
+    "sys_path_hardened": False,
+    "warnings": [],
+}
+
+
+def _configure_utf8_env() -> None:
+    if "PYTHONUTF8" in os.environ:
+        STATE["python_utf8_set"] = "preexisting"
+    else:
+        os.environ["PYTHONUTF8"] = "1"
+        STATE["python_utf8_set"] = True
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+
+
+def _reconfigure_stream(name: str, key: str) -> None:
+    stream = getattr(sys, name, None)
+    reconfigure = getattr(stream, "reconfigure", None)
+    if not callable(reconfigure):
+        STATE[key] = "not_a_text_wrapper"
+        return
+    try:
+        reconfigure(encoding="utf-8", errors="replace")
+        STATE[key] = True
+    except Exception as exc:  # noqa: BLE001 - bootstrap must never raise
+        STATE[key] = False
+        STATE["warnings"].append(f"{name}.reconfigure failed: {exc}")
+
+
+def _harden_sys_path() -> None:
+    try:
+        src_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        if src_root and src_root not in sys.path:
+            sys.path.insert(0, src_root)
+        # Strip current-directory entries so a user's local module cannot
+        # shadow package modules with common names (utils, proxy, ui, ...).
+        sys.path[:] = [entry for entry in sys.path if entry not in ("", ".")]
+        STATE["sys_path_hardened"] = True
+    except Exception as exc:  # noqa: BLE001
+        STATE["warnings"].append(f"sys.path hardening failed: {exc}")
+
+
+def _load_dotenv() -> None:
+    try:
+        from .dotenv import load_default_files
+
+        STATE["dotenv"] = load_default_files()
+    except Exception as exc:  # noqa: BLE001 - .env loading must never break startup
+        STATE["warnings"].append(f".env load failed: {exc}")
+
+
+def install() -> dict[str, Any]:
+    """Idempotently apply the bootstrap and return :data:`STATE`."""
+    if getattr(sys, "_pf_agent_bootstrapped", False):
+        STATE["already_installed"] = True
+        return STATE
+
+    STATE["already_installed"] = False
+    STATE["warnings"] = []
+    try:
+        _configure_utf8_env()
+        _reconfigure_stream("stdout", "stdout_reconfigured")
+        _reconfigure_stream("stderr", "stderr_reconfigured")
+        _reconfigure_stream("stdin", "stdin_reconfigured")
+        _harden_sys_path()
+        _load_dotenv()
+    except Exception as exc:  # noqa: BLE001 - defense in depth
+        STATE["warnings"].append(f"bootstrap error: {exc}")
+
+    sys._pf_agent_bootstrapped = True  # type: ignore[attr-defined]
+    return STATE
+
+
+# Apply automatically on import so entry points only need `import _bootstrap`.
+install()
+
+
+__all__ = ["STATE", "install"]

proseforge_agent/agent/__init__.py

@@ -0,0 +1,123 @@
+"""Agent runtime interfaces."""
+
+from .events import BackgroundJobRunner, EventBus, EventRecord, JobResult, ToolOutputChunk
+from .eval import EvalHarness, EvalReport, EvalSuite, EvalTaskResult, GoldenTask
+from .attachments import AttachmentIngestResult, AttachmentIngestor
+from .audit import AuditStep, AuditTrailStore, ReplayResult
+from .execution_guard import ExecutionGuard, ExecutionGuardResult, ExecutionPolicy
+from .function_calling import (
+    ProviderToolCall,
+    StructuredToolAdapter,
+    StructuredToolResult,
+    ToolCallLoop,
+    ToolLoopResult,
+)
+from .kernel import AgentKernel
+from .intent_router import IntentDecision, IntentRouter
+from .types import AgentIntent, AgentTurnRequest, AgentTurnResult, ToolCallResult
+from .control import ControlSignal, ControlToken
+from .context_window import ContextUsageReport, ContextWindowManager
+from .degradation import CapabilityReport, CapabilityRuntime, FeatureCheck, FeatureDeclaration, FeatureLevel
+from .offline import OfflineDecision, OfflinePolicy
+from .permissions import PERMISSION_LEVELS, PermissionDecision, PermissionPolicy
+from .profiles import AgentProfile, AgentProfileRegistry
+from .provider_fallback import ProviderFallbackAttempt, ProviderFallbackChain, ProviderFallbackResult
+from .prompt_templates import (
+    PromptTemplate,
+    PromptTemplateRegistry,
+    PromptTemplateValidation,
+    PromptTemplateValidationError,
+)
+from .request_cache import CachedResponse, RequestCache, RequestCacheKey
+from .sandbox import Approval, ExecRequest, ExecResult, Sandbox
+from .subagent import Scope, SubAgentResult, SubAgentRunner
+from .structured_output import (
+    StructuredOutputRepairResult,
+    repair_structured_output,
+    validate_or_repair,
+)
+from .tools import (
+    AgentTool,
+    ToolContext,
+    ToolRegistry,
+    ToolResult,
+    default_tool_registry,
+    general_tool_registry,
+    register_writing_domain_tools,
+)
+
+__all__ = [
+    "BackgroundJobRunner",
+    "AttachmentIngestResult",
+    "AttachmentIngestor",
+    "AuditStep",
+    "AuditTrailStore",
+    "EvalHarness",
+    "EvalReport",
+    "EvalSuite",
+    "EvalTaskResult",
+    "GoldenTask",
+    "EventBus",
+    "EventRecord",
+    "ExecutionGuard",
+    "ExecutionGuardResult",
+    "ExecutionPolicy",
+    "ProviderToolCall",
+    "StructuredToolAdapter",
+    "StructuredToolResult",
+    "ToolCallLoop",
+    "ToolLoopResult",
+    "ToolOutputChunk",
+    "AgentKernel",
+    "IntentDecision",
+    "IntentRouter",
+    "AgentIntent",
+    "AgentTurnRequest",
+    "AgentTurnResult",
+    "ToolCallResult",
+    "ControlSignal",
+    "ControlToken",
+    "ContextUsageReport",
+    "ContextWindowManager",
+    "CapabilityReport",
+    "CapabilityRuntime",
+    "FeatureCheck",
+    "FeatureDeclaration",
+    "FeatureLevel",
+    "OfflineDecision",
+    "OfflinePolicy",
+    "PERMISSION_LEVELS",
+    "PermissionDecision",
+    "PermissionPolicy",
+    "AgentProfile",
+    "AgentProfileRegistry",
+    "ProviderFallbackAttempt",
+    "ProviderFallbackChain",
+    "ProviderFallbackResult",
+    "PromptTemplate",
+    "PromptTemplateRegistry",
+    "PromptTemplateValidation",
+    "PromptTemplateValidationError",
+    "CachedResponse",
+    "RequestCache",
+    "RequestCacheKey",
+    "ReplayResult",
+    "Approval",
+    "ExecRequest",
+    "ExecResult",
+    "Sandbox",
+    "Scope",
+    "SubAgentResult",
+    "SubAgentRunner",
+    "StructuredOutputRepairResult",
+    "AgentTool",
+    "ToolContext",
+    "ToolRegistry",
+    "ToolResult",
+    "JobResult",
+    "default_tool_registry",
+    "general_tool_registry",
+    "register_writing_domain_tools",
+    "repair_structured_output",
+    "validate_or_repair",
+]

proseforge_agent/agent/artifacts.py

@@ -0,0 +1,160 @@
+"""Bounded artifact storage for large tool results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import json
+from pathlib import Path
+import re
+from typing import Any
+
+from .tools import ToolResult
+
+
+@dataclass(frozen=True)
+class ArtifactRef:
+    """Portable reference to a stored tool artifact."""
+
+    id: str
+    kind: str
+    path: str
+    content_type: str
+    size_bytes: int
+    metadata: dict[str, Any] = field(default_factory=dict)
+    redaction_applied: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "kind": self.kind,
+            "path": self.path,
+            "content_type": self.content_type,
+            "size_bytes": self.size_bytes,
+            "metadata": self.metadata,
+            "redaction_applied": self.redaction_applied,
+        }
+
+
+class ArtifactStore:
+    """Path-contained local store for redacted tool artifacts."""
+
+    def __init__(self, root: str | Path, *, output_limit: int = 4096) -> None:
+        self.root = Path(root)
+        self.base = self.root / "tool_artifacts"
+        self.output_limit = output_limit
+        self.base.mkdir(parents=True, exist_ok=True)
+
+    def write(self, kind: str, content: str | bytes, metadata: dict[str, Any] | None = None) -> ArtifactRef:
+        metadata = dict(metadata or {})
+        content_type = str(
+            metadata.get("content_type")
+            or ("application/octet-stream" if isinstance(content, bytes) else "text/plain")
+        )
+        redaction_applied = False
+        if isinstance(content, bytes):
+            stored = content
+            suffix = ".bin"
+        else:
+            text, redaction_applied = _redact(content)
+            stored = text.encode("utf-8")
+            suffix = ".txt"
+        digest = hashlib.sha256(stored).hexdigest()
+        artifact_id = f"artifact-{kind}-{digest[:16]}"
+        artifact_path = self._contained_path(f"{artifact_id}{suffix}")
+        artifact_path.write_bytes(stored)
+        ref = ArtifactRef(
+            id=artifact_id,
+            kind=kind,
+            path=str(artifact_path.relative_to(self.root)),
+            content_type=content_type,
+            size_bytes=len(stored),
+            metadata=metadata,
+            redaction_applied=redaction_applied,
+        )
+        self._metadata_path(artifact_id).write_text(
+            json.dumps(ref.to_dict(), indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+        return ref
+
+    def read(self, artifact_id: str) -> str | bytes:
+        ref = self.get(artifact_id)
+        if ref is None:
+            raise FileNotFoundError(artifact_id)
+        path = self._contained_path(Path(ref.path).name)
+        content = path.read_bytes()
+        if ref.content_type.startswith("text/"):
+            return content.decode("utf-8")
+        return content
+
+    def get(self, artifact_id: str) -> ArtifactRef | None:
+        path = self._metadata_path(artifact_id)
+        if not path.exists():
+            return None
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return ArtifactRef(
+            id=str(payload["id"]),
+            kind=str(payload["kind"]),
+            path=str(payload["path"]),
+            content_type=str(payload["content_type"]),
+            size_bytes=int(payload["size_bytes"]),
+            metadata=dict(payload.get("metadata") or {}),
+            redaction_applied=bool(payload.get("redaction_applied", False)),
+        )
+
+    def list(self) -> list[ArtifactRef]:
+        refs = []
+        for path in sorted(self.base.glob("*.meta.json")):
+            refs.append(self.get(path.name.removesuffix(".meta.json")))
+        return [ref for ref in refs if ref is not None]
+
+    def cleanup(self, *, keep_last: int = 100) -> list[str]:
+        refs = self.list()
+        removed: list[str] = []
+        for ref in refs[:-keep_last]:
+            artifact_path = self._contained_path(Path(ref.path).name)
+            metadata_path = self._metadata_path(ref.id)
+            if artifact_path.exists():
+                artifact_path.unlink()
+            if metadata_path.exists():
+                metadata_path.unlink()
+            removed.append(ref.id)
+        return removed
+
+    def _metadata_path(self, artifact_id: str) -> Path:
+        return self._contained_path(f"{artifact_id}.meta.json")
+
+    def _contained_path(self, name: str) -> Path:
+        root = self.base.resolve()
+        path = (self.base / name).resolve()
+        if path != root and root not in path.parents:
+            raise ValueError("artifact path escapes store")
+        return path
+
+
+def summarize_tool_output(content: str | bytes, *, store: ArtifactStore, kind: str = "tool") -> ToolResult:
+    ref = store.write(kind, content, {})
+    if isinstance(content, bytes):
+        summary = f"{kind} binary artifact {ref.id}"
+        truncated = True
+    else:
+        summary = _redact(content)[0][: store.output_limit]
+        truncated = len(content) > store.output_limit
+    return ToolResult(
+        ok=True,
+        output=summary,
+        summary=summary,
+        artifact_refs=[ref],
+        truncated=truncated,
+        redaction_applied=ref.redaction_applied,
+        provenance="artifact_store",
+    )
+
+
+def _redact(text: str) -> tuple[str, bool]:
+    pattern = re.compile(r"(?i)(token|secret|api_key|password)=\S+")
+    return pattern.sub(r"\1=[redacted]", text), bool(pattern.search(text))
+
+
+__all__ = ["ArtifactRef", "ArtifactStore", "summarize_tool_output"]

proseforge_agent/agent/attachments.py

@@ -0,0 +1,282 @@
+"""Deterministic attachment ingestion for chat and project context."""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+import struct
+import zipfile
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+from xml.etree import ElementTree
+
+from ..chat.transcript import append_jsonl
+from ..errors import ConfigurationError
+from ..novel.artifacts import ArtifactGraphStore, ArtifactRecord
+
+UTC = timezone.utc
+
+
+TEXT_EXTENSIONS = {".txt": "text", ".md": "markdown", ".markdown": "markdown"}
+TABLE_EXTENSIONS = {".csv": "csv", ".xlsx": "excel", ".xlsm": "excel"}
+DOCUMENT_EXTENSIONS = {".pdf": "pdf", ".docx": "docx"}
+IMAGE_EXTENSIONS = {".png": "image", ".jpg": "image", ".jpeg": "image", ".webp": "image"}
+SUPPORTED_EXTENSIONS = set(TEXT_EXTENSIONS) | set(TABLE_EXTENSIONS) | set(DOCUMENT_EXTENSIONS) | set(IMAGE_EXTENSIONS)
+
+
+@dataclass(frozen=True)
+class AttachmentIngestResult:
+    """One ingested attachment and its persisted project artifacts."""
+
+    id: str
+    status: str
+    kind: str
+    source_path: Path
+    text: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+    artifact_path: Path = Path()
+    searchable_path: Path | None = None
+    memory_candidate_path: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["source_path"] = str(self.source_path)
+        payload["artifact_path"] = str(self.artifact_path)
+        payload["searchable_path"] = str(self.searchable_path) if self.searchable_path else None
+        payload["memory_candidate_path"] = str(self.memory_candidate_path) if self.memory_candidate_path else None
+        return payload
+
+
+class AttachmentIngestor:
+    """Extract searchable text and metadata from supported attachments."""
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        vision_describer: Callable[[Path], str] | None = None,
+    ) -> None:
+        self.root = Path(root)
+        self.vision_describer = vision_describer
+
+    def ingest_file(self, source: str | Path, *, slug: str) -> AttachmentIngestResult:
+        path = Path(source)
+        self._require_source(path)
+        if path.suffix.lower() in IMAGE_EXTENSIONS:
+            return self.ingest_image(path, slug=slug)
+        text, kind, metadata, warnings = self._extract(path)
+        return self._persist(path, slug=slug, kind=kind, text=text, metadata=metadata, warnings=warnings)
+
+    def ingest_image(self, source: str | Path, *, slug: str) -> AttachmentIngestResult:
+        path = Path(source)
+        self._require_source(path)
+        metadata = _image_metadata(path)
+        text = self.vision_describer(path) if self.vision_describer else ""
+        warnings = [] if text else ["image description provider not configured"]
+        return self._persist(path, slug=slug, kind="image", text=text, metadata=metadata, warnings=warnings)
+
+    def ingest_folder(self, source: str | Path, *, slug: str) -> list[AttachmentIngestResult]:
+        folder = Path(source)
+        if not folder.is_dir():
+            raise ConfigurationError(f"attachment folder does not exist: {folder}")
+        results: list[AttachmentIngestResult] = []
+        for item in sorted(folder.iterdir(), key=lambda path: path.name):
+            if item.is_file() and item.suffix.lower() in SUPPORTED_EXTENSIONS:
+                results.append(self.ingest_file(item, slug=slug))
+        return results
+
+    def _extract(self, path: Path) -> tuple[str, str, dict[str, Any], list[str]]:
+        suffix = path.suffix.lower()
+        metadata = {"extension": suffix, "size_bytes": path.stat().st_size}
+        if suffix in TEXT_EXTENSIONS:
+            return path.read_text(encoding="utf-8"), TEXT_EXTENSIONS[suffix], metadata, []
+        if suffix == ".csv":
+            return _extract_csv(path), "csv", metadata, []
+        if suffix in {".xlsx", ".xlsm"}:
+            text, warnings = _extract_excel(path)
+            return text, "excel", metadata, warnings
+        if suffix == ".docx":
+            return _extract_docx(path), "docx", metadata, []
+        if suffix == ".pdf":
+            text, warnings = _extract_pdf(path)
+            return text, "pdf", metadata, warnings
+        raise ConfigurationError(f"unsupported attachment format: {suffix}")
+
+    def _persist(
+        self,
+        source_path: Path,
+        *,
+        slug: str,
+        kind: str,
+        text: str,
+        metadata: dict[str, Any],
+        warnings: list[str],
+    ) -> AttachmentIngestResult:
+        project_root = self.root / "projects" / slug
+        attachment_id = f"attachment_{_sha256(source_path.read_bytes())[:12]}"
+        artifact_path = project_root / "attachments" / f"{attachment_id}.json"
+        searchable_path = project_root / "searchable" / f"{attachment_id}.txt"
+        candidate_path = self.root / "memory_candidates" / "projects" / f"{slug}.jsonl"
+        searchable_text = text if text.strip() else _metadata_text(metadata)
+
+        artifact_path.parent.mkdir(parents=True, exist_ok=True)
+        searchable_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "id": attachment_id,
+            "kind": kind,
+            "source": str(source_path),
+            "text": text,
+            "metadata": metadata,
+            "warnings": warnings,
+            "created_at": datetime.now(UTC).isoformat(),
+        }
+        artifact_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        searchable_path.write_text(searchable_text, encoding="utf-8")
+        append_jsonl(
+            candidate_path,
+            {
+                "id": f"memcand_{attachment_id}",
+                "kind": "attachment",
+                "project_slug": slug,
+                "scope": "project",
+                "source": str(source_path),
+                "text": searchable_text[:2000],
+                "status": "candidate",
+                "created_at": datetime.now(UTC).isoformat(),
+            },
+        )
+        ArtifactGraphStore(self.root, slug=slug).add(
+            ArtifactRecord(
+                id=attachment_id,
+                type=f"attachment:{kind}",
+                generated=[str(searchable_path)],
+                checksum=_sha256(artifact_path.read_bytes()),
+                provider="local",
+                prompt_version="attachment-ingestion-v1",
+            )
+        )
+        return AttachmentIngestResult(
+            id=attachment_id,
+            status="degraded" if warnings and not text.strip() else "ok",
+            kind=kind,
+            source_path=source_path,
+            text=text,
+            metadata=metadata,
+            artifact_path=artifact_path,
+            searchable_path=searchable_path,
+            memory_candidate_path=candidate_path,
+            warnings=warnings,
+        )
+
+    @staticmethod
+    def _require_source(path: Path) -> None:
+        if not path.is_file():
+            raise ConfigurationError(f"attachment file does not exist: {path}")
+
+
+def _extract_csv(path: Path) -> str:
+    rows: list[str] = []
+    with path.open("r", encoding="utf-8", newline="") as handle:
+        reader = csv.reader(handle)
+        for row in reader:
+            rows.append("\t".join(row))
+    return "\n".join(rows) + ("\n" if rows else "")
+
+
+def _extract_docx(path: Path) -> str:
+    with zipfile.ZipFile(path) as archive:
+        try:
+            raw = archive.read("word/document.xml")
+        except KeyError:
+            return ""
+    root = ElementTree.fromstring(raw)
+    namespace = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
+    texts = [node.text or "" for node in root.iter(f"{namespace}t")]
+    return "\n".join(text for text in texts if text)
+
+
+def _extract_pdf(path: Path) -> tuple[str, list[str]]:
+    try:
+        from pypdf import PdfReader  # type: ignore
+    except Exception:
+        try:
+            from PyPDF2 import PdfReader  # type: ignore
+        except Exception:
+            return "", ["pdf text extraction requires pypdf or PyPDF2"]
+    try:
+        reader = PdfReader(str(path))
+        text = "\n".join(page.extract_text() or "" for page in reader.pages)
+    except Exception as exc:
+        return "", [f"pdf text extraction failed: {exc}"]
+    return text, []
+
+
+def _extract_excel(path: Path) -> tuple[str, list[str]]:
+    try:
+        from openpyxl import load_workbook  # type: ignore
+    except Exception:
+        return "", ["excel table extraction requires openpyxl"]
+    workbook = load_workbook(path, read_only=True, data_only=True)
+    lines: list[str] = []
+    for sheet in workbook.worksheets:
+        lines.append(f"# {sheet.title}")
+        for row in sheet.iter_rows(values_only=True):
+            values = ["" if value is None else str(value) for value in row]
+            if any(values):
+                lines.append("\t".join(values))
+    return "\n".join(lines) + ("\n" if lines else ""), []
+
+
+def _image_metadata(path: Path) -> dict[str, Any]:
+    data = path.read_bytes()
+    metadata: dict[str, Any] = {
+        "extension": path.suffix.lower(),
+        "size_bytes": len(data),
+    }
+    if data.startswith(b"\x89PNG\r\n\x1a\n") and len(data) >= 24:
+        width, height = struct.unpack(">II", data[16:24])
+        metadata.update({"format": "png", "width": width, "height": height})
+        return metadata
+    if data.startswith(b"\xff\xd8"):
+        size = _jpeg_size(data)
+        metadata.update({"format": "jpeg"})
+        if size:
+            metadata.update({"width": size[0], "height": size[1]})
+        return metadata
+    metadata["format"] = path.suffix.lower().lstrip(".") or "unknown"
+    return metadata
+
+
+def _jpeg_size(data: bytes) -> tuple[int, int] | None:
+    index = 2
+    while index + 9 < len(data):
+        if data[index] != 0xFF:
+            index += 1
+            continue
+        marker = data[index + 1]
+        block_length = int.from_bytes(data[index + 2 : index + 4], "big")
+        if marker in {0xC0, 0xC2}:
+            height = int.from_bytes(data[index + 5 : index + 7], "big")
+            width = int.from_bytes(data[index + 7 : index + 9], "big")
+            return width, height
+        index += 2 + block_length
+    return None
+
+
+def _metadata_text(metadata: dict[str, Any]) -> str:
+    return "\n".join(f"{key}: {value}" for key, value in sorted(metadata.items())) + "\n"
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+__all__ = [
+    "AttachmentIngestResult",
+    "AttachmentIngestor",
+    "SUPPORTED_EXTENSIONS",
+]