traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/agent.py

@@ -0,0 +1,680 @@
+"""The agent loop: Claude + tools, streaming, with append-only history."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+import anthropic
+
+from traceforge import context as ctxmod
+from traceforge.approval import ApprovalPolicy
+from traceforge.config import Settings
+from traceforge.prompts import system_prompt
+from traceforge.tools.base import (
+    Registry,
+    Tool,
+    ToolContext,
+    ToolError,
+    ToolKind,
+    ToolOutput,
+    render,
+    spill,
+    to_text,
+    validate_arguments,
+)
+from traceforge.tools.batch import (
+    EXCLUSIVE,
+    READ,
+    WRITE,
+    CallPlan,
+    path_key,
+    read_only_command,
+    run_batch,
+)
+
+# A tool result is plain text, or a list of content blocks (text and images).
+ToolContent = str | list[dict[str, Any]]
+
+FALLBACK_BETA = "server-side-fallback-2026-07-01"
+# Models that accept adaptive thinking + effort and server-side "default" fallbacks.
+_FALLBACK_MODELS = {"claude-opus-5-5", "claude-opus-5", "claude-fable-5-1", "claude-sonnet-5-5"}
+_LEGACY_THINKING = ("claude-haiku-4", "claude-sonnet-4-5", "claude-opus-4-5", "claude-3")
+
+
+@dataclass
+class AgentEvent:
+    kind: str  # text | thinking | tool_call | tool_result | usage | status | error | done
+    data: Any = None
+
+
+EventSink = Callable[[AgentEvent], Awaitable[None] | None]
+
+
+async def _emit(sink: EventSink | None, kind: str, data: Any = None) -> None:
+    if sink is None:
+        return
+    result = sink(AgentEvent(kind, data))
+    if asyncio.iscoroutine(result):
+        await result
+
+
+class AgentError(RuntimeError):
+    """The model call failed in a way the loop cannot recover from."""
+
+
+log = logging.getLogger("traceforge.agent")
+
+# Errors that mean the prompt no longer fits the model's context window.
+_OVERFLOW = re.compile(
+    r"prompt is too long|context.length.exceeded|maximum context length|too many tokens|"
+    r"context window|input is too long",
+    re.IGNORECASE,
+)
+
+
+class ToolExecutor(Protocol):
+    def definitions(self) -> list[dict[str, Any]]: ...
+
+    async def execute(
+        self, name: str, arguments: dict[str, Any], tool_use_id: str
+    ) -> tuple[ToolContent, bool]: ...
+
+    def parallel_safe(self, name: str) -> bool: ...
+
+
+def plan_call(tool: Tool | None, arguments: dict[str, Any], workspace: str | None) -> CallPlan:
+    """How a call may be scheduled alongside the other calls of the same model step."""
+    if tool is None:
+        return CallPlan(EXCLUSIVE)
+    if tool.schedule is not None:
+        kind = tool.schedule(arguments)
+    elif tool.kind is ToolKind.READ:
+        kind = READ
+    elif tool.kind is ToolKind.WRITE:
+        kind = WRITE
+    elif tool.kind is ToolKind.SHELL and read_only_command(arguments.get("command")):
+        kind = READ
+    else:
+        kind = EXCLUSIVE
+    target = arguments.get(tool.target_arg or "path") if kind in (READ, WRITE) else None
+    return CallPlan(kind, path_key(target, workspace))
+
+
+class LocalExecutor:
+    """Runs tools in this process, gated by the approval policy."""
+
+    def __init__(self, registry: Registry, context: ToolContext, policy: ApprovalPolicy):
+        self.registry = registry
+        self.context = context
+        self.policy = policy
+
+    def definitions(self) -> list[dict[str, Any]]:
+        return self.registry.definitions(eager=True)
+
+    def parallel_safe(self, name: str) -> bool:
+        tool = self.registry.get(name)
+        return tool is not None and tool.kind is ToolKind.READ
+
+    def plan(self, name: str, arguments: dict[str, Any]) -> CallPlan:
+        return plan_call(self.registry.get(name), arguments, str(self.context.workspace))
+
+    async def execute(
+        self, name: str, arguments: dict[str, Any], tool_use_id: str
+    ) -> tuple[ToolContent, bool]:
+        tool = self.registry.get(name)
+        if tool is None:
+            known = ", ".join(sorted(self.registry.names()))
+            return f"unknown tool {name!r}; available tools: {known}", True
+        problems = validate_arguments(tool.input_schema, arguments)
+        if problems:
+            return "invalid arguments: " + "; ".join(problems), True
+        allowed, reason = await self.policy.check(tool, arguments)
+        if not allowed:
+            return f"not run: {reason}", True
+        try:
+            result = await tool.call(arguments, self.context)
+        except ToolError as exc:
+            return to_text(str(exc)), True
+        except Exception as exc:  # a tool bug must not end the session
+            return to_text(f"{type(exc).__name__}: {exc}"), True
+        if isinstance(result, ToolOutput) and result.images:
+            return result.blocks(), False
+        text = render(result.text if isinstance(result, ToolOutput) else result)
+        if tool.spill:
+            return spill(text, self.context, name, tool_use_id), False
+        return to_text(text), False
+
+
+_USAGE_FIELDS = (
+    "input_tokens",
+    "output_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+)
+
+
+def _model_of(response: Any, fallback: Any) -> str:
+    """The model that answered: what the response says, else the route that was asked."""
+    name = getattr(response, "model", None)
+    if isinstance(name, str) and name:
+        return name
+    return str(getattr(fallback, "model", fallback) or "")
+
+
+@dataclass
+class Usage:
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    requests: int = 0
+
+    def __post_init__(self) -> None:
+        # Tokens per model id (not a dataclass field, so code that sums the counters
+        # above keeps working); the cost meter prices each model separately.
+        self.by_model: dict[str, dict[str, int]] = {}
+
+    def add(self, usage: Any, model: str = "") -> None:
+        self.requests += 1
+        for name in _USAGE_FIELDS:
+            setattr(self, name, getattr(self, name) + int(getattr(usage, name, 0) or 0))
+        if model:
+            slot = self.by_model.setdefault(model, dict.fromkeys((*_USAGE_FIELDS, "requests"), 0))
+            slot["requests"] += 1
+            for name in _USAGE_FIELDS:
+                slot[name] += int(getattr(usage, name, 0) or 0)
+
+    def merge(self, other: Usage) -> None:
+        for name in (*_USAGE_FIELDS, "requests"):
+            setattr(self, name, getattr(self, name) + getattr(other, name))
+        for model, counts in other.by_model.items():
+            slot = self.by_model.setdefault(model, dict.fromkeys(counts, 0))
+            for name, value in counts.items():
+                slot[name] = slot.get(name, 0) + value
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {name: getattr(self, name) for name in (*_USAGE_FIELDS, "requests")}
+        if self.by_model:
+            data["by_model"] = {m: dict(c) for m, c in self.by_model.items()}
+        return data
+
+
+@dataclass
+class TurnResult:
+    text: str
+    stop_reason: str | None
+    usage: Usage
+    tool_calls: int = 0
+    refusal: dict | None = None
+    messages_added: int = 0
+
+
+@dataclass
+class Agent:
+    settings: Settings
+    executor: ToolExecutor
+    mode: str = "agent"
+    client: Any = None  # anthropic.AsyncAnthropic or a compatible fake
+    extra_instructions: str = ""
+    usage: Usage = field(default_factory=Usage)
+    # Context management: the summary/cutoff for the current thread, the todo list,
+    # and where full transcripts of compacted history are written.
+    compaction: ctxmod.Compaction = field(default_factory=ctxmod.Compaction)
+    todos: list[dict[str, Any]] = field(default_factory=list)
+    history_dir: Path | None = None
+    retry_delays: tuple[float, ...] = (2.0, 5.0, 15.0)
+
+    def __post_init__(self) -> None:
+        from traceforge import routing
+
+        self.route = routing.route(self.settings, routing.role_for_mode(self.mode))
+        self.escalated: routing.Route | None = None  # set for the rest of a failing turn
+        if self.client is None:
+            from traceforge.providers import make_client, provider_for
+
+            self.client = make_client(
+                provider_for(self.settings.model, self.settings.provider), self.settings
+            )
+        self.system = system_prompt(
+            self.mode, self.extra_instructions or self.settings.extra_instructions
+        )
+
+    # ---------------------------------------------------------------- request
+    @property
+    def current_route(self):
+        return self.escalated or self.route
+
+    def _request(self, messages: list[dict[str, Any]]) -> dict[str, Any]:
+        model = self.current_route.model
+        request: dict[str, Any] = {
+            "model": model,
+            "max_tokens": self.settings.max_tokens,
+            "system": [{"type": "text", "text": self.system}],
+            "tools": self.executor.definitions(),
+            "messages": messages,
+            "cache_control": {"type": "ephemeral"},
+        }
+        if not model.startswith(_LEGACY_THINKING):
+            request["thinking"] = {"type": "adaptive", "display": self.settings.thinking_display}
+            request["output_config"] = {"effort": self.current_route.effort}
+        if self.settings.use_fallbacks() and model in _FALLBACK_MODELS:
+            request["extra_headers"] = {"anthropic-beta": FALLBACK_BETA}
+            request["extra_body"] = {"fallbacks": "default"}
+        return request
+
+    async def _stream_once(self, messages: list[dict[str, Any]], sink: EventSink | None):
+        request = self._request(messages)
+        attempts = 0
+        retries = 0
+        while True:
+            try:
+                async with self.client.messages.stream(**request) as stream:
+                    async for event in stream:
+                        etype = getattr(event, "type", None)
+                        if etype == "text":
+                            await _emit(sink, "text", event.text)
+                        elif etype == "thinking":
+                            await _emit(sink, "thinking", event.thinking)
+                    return await stream.get_final_message()
+            except ValueError:
+                # Tool input JSON the SDK could not parse at all: re-issue the turn (bounded).
+                attempts += 1
+                if attempts > 2:
+                    raise AgentError(
+                        "the model produced unparseable tool input three times"
+                    ) from None
+                await _emit(sink, "status", "retrying a malformed tool call")
+            except TypeError as exc:
+                if "authentication method" not in str(exc):
+                    raise
+                raise AgentError(
+                    "No API key found. Set ANTHROPIC_API_KEY (or run `ant auth login`), put it in a "
+                    ".env file, or use a hosted server with --server."
+                ) from exc
+            except anthropic.AuthenticationError as exc:
+                raise AgentError(
+                    "Authentication failed. Set ANTHROPIC_API_KEY (or run `ant auth login`), "
+                    "or use a hosted server with --server."
+                ) from exc
+            except anthropic.BadRequestError as exc:
+                if "fallbacks" in request.get("extra_body", {}) and "fallback" in str(exc).lower():
+                    request.pop("extra_body", None)
+                    request.pop("extra_headers", None)
+                    await _emit(
+                        sink, "status", "server-side fallback unavailable; continuing without it"
+                    )
+                    continue
+                raise AgentError(f"The API rejected the request: {exc.message}") from exc
+            except anthropic.RateLimitError as exc:
+                if await self._retry_wait(retries, sink, "rate limited"):
+                    retries += 1
+                    continue
+                raise AgentError(
+                    f"Rate limited by the API: {exc.message}. Try again shortly."
+                ) from exc
+            except anthropic.APIStatusError as exc:
+                transient = exc.status_code >= 500 or exc.status_code in (408, 409)
+                if transient and await self._retry_wait(
+                    retries, sink, f"API error {exc.status_code}"
+                ):
+                    retries += 1
+                    continue
+                raise AgentError(f"API error {exc.status_code}: {exc.message}") from exc
+            except anthropic.APIConnectionError as exc:
+                if await self._retry_wait(retries, sink, "connection dropped"):
+                    retries += 1
+                    continue
+                raise AgentError(f"Could not reach the API: {exc}") from exc
+
+    async def _retry_wait(self, retries: int, sink: EventSink | None, why: str) -> bool:
+        """Wait before retrying a transient failure; False once the retries are used up.
+
+        Nothing has been appended to the history yet, so repeating the call is safe.
+        """
+        if retries >= len(self.retry_delays):
+            return False
+        delay = self.retry_delays[retries]
+        await _emit(
+            sink,
+            "status",
+            f"{why}; retrying in {delay:g}s ({retries + 1}/{len(self.retry_delays)})",
+        )
+        await asyncio.sleep(delay)
+        return True
+
+    # ----------------------------------------------------------------- context
+    def context_window(self) -> int:
+        return self.settings.context_window_tokens()
+
+    def _view(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return ctxmod.view(messages, self.compaction, self.todos)
+
+    def _prompt_tokens(self, view: list[dict[str, Any]]) -> int:
+        tools = len(json.dumps(self.executor.definitions(), default=str))
+        return ctxmod.estimate_tokens(view) + (len(self.system) + tools) // ctxmod.CHARS_PER_TOKEN
+
+    async def _maybe_compact(
+        self, messages: list[dict[str, Any]], sink: EventSink | None, *, force: bool = False
+    ) -> bool:
+        window = self.context_window()
+        limit = int(window * self.settings.compact_at)
+        used = self._prompt_tokens(self._view(messages))
+        if not force and used < limit:
+            return False
+        return await self.compact(messages, sink, reason=f"~{used} tokens of {window}")
+
+    async def compact(
+        self, messages: list[dict[str, Any]], sink: EventSink | None = None, reason: str = ""
+    ) -> bool:
+        """Summarise older history so the view fits again. Returns False if nothing to do."""
+        keep = int(self.context_window() * self.settings.compact_keep)
+        cutoff = ctxmod.choose_cutoff(messages, self.compaction.cutoff, keep)
+        if cutoff is None:
+            return False
+        older = messages[self.compaction.cutoff : cutoff]
+        await _emit(
+            sink,
+            "status",
+            f"compacting context ({reason or 'requested'}): summarising {len(older)} messages",
+        )
+        transcript = ctxmod.render_transcript(older)
+        if self.compaction.summary:
+            transcript = (
+                "Summary of the history before these messages:\n"
+                + self.compaction.summary
+                + "\n\n# Messages since that summary\n\n"
+                + transcript
+            )
+        budget = int(self.context_window() * 0.5) * ctxmod.CHARS_PER_TOKEN
+        if len(transcript) > budget:
+            transcript = "[older part omitted]\n" + transcript[-budget:]
+        if self.todos:
+            transcript += "\n\nCurrent todo list:\n" + json.dumps(self.todos, indent=1)
+        archive = None
+        if self.history_dir is not None:
+            try:
+                self.history_dir.mkdir(parents=True, exist_ok=True)
+                stamp = time.strftime("%Y%m%d-%H%M%S")
+                archive = self.history_dir / f"history-{stamp}-{self.compaction.count + 1}.md"
+                archive.write_text(
+                    ctxmod.render_transcript(older, result_chars=0, input_chars=0),
+                    encoding="utf-8",
+                )
+            except OSError:
+                archive = None
+        from traceforge import routing
+
+        compact = routing.route(self.settings, "compact")
+        request = {
+            "model": compact.model,
+            "max_tokens": min(self.settings.max_tokens, 12_000),
+            "system": [{"type": "text", "text": ctxmod.SUMMARY_SYSTEM}],
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "Summarise this working history.\n\n<history>\n"
+                            + transcript
+                            + "\n</history>",
+                        }
+                    ],
+                }
+            ],
+        }
+        try:
+            async with self.client.messages.stream(**request) as stream:
+                async for _ in stream:
+                    pass
+                response = await stream.get_final_message()
+        except Exception as exc:  # compaction failing must not end the session
+            log.warning("compaction failed: %s", exc)
+            await _emit(sink, "status", f"context compaction failed: {exc}")
+            return False
+        self.usage.add(response.usage, _model_of(response, self.route.model))
+        summary = "".join(
+            getattr(b, "text", "") for b in response.content if getattr(b, "type", "") == "text"
+        ).strip()
+        if not summary:
+            return False
+        files = list(self.compaction.history_files)
+        if archive is not None:
+            files.append(self._display(archive))
+        self.compaction = ctxmod.Compaction(cutoff, summary, files, self.compaction.count + 1)
+        await _emit(
+            sink,
+            "compacted",
+            {"cutoff": cutoff, "messages_summarised": len(older), "archive": files[-1:] or None},
+        )
+        return True
+
+    def _display(self, path: Path) -> str:
+        workspace = getattr(getattr(self.executor, "context", None), "workspace", None)
+        if workspace is not None:
+            try:
+                return path.relative_to(workspace).as_posix()
+            except ValueError:
+                pass
+        return str(path)
+
+    # --------------------------------------------------------------------- run
+    async def run(
+        self,
+        messages: list[dict[str, Any]],
+        user_content: str | list[dict[str, Any]],
+        sink: EventSink | None = None,
+        checkpoint: Callable[[list[dict[str, Any]]], None] | None = None,
+    ) -> TurnResult:
+        """Run one user turn to completion. ``messages`` is extended in place."""
+        start = len(messages)
+        content = (
+            [{"type": "text", "text": user_content}]
+            if isinstance(user_content, str)
+            else user_content
+        )
+        # A turn that crashed or was killed may have left tool calls unanswered.
+        _close_dangling_tool_uses(messages)
+        if messages and messages[-1]["role"] == "user":
+            # e.g. after an interruption left tool results as the last message
+            messages[-1]["content"].extend(content)
+        else:
+            messages.append({"role": "user", "content": content})
+        turn_usage = Usage()
+        tool_calls = 0
+        final_text: list[str] = []
+        stop_reason: str | None = None
+        refusal = None
+        self.escalated = None
+        failures = 0  # consecutive failed tool calls in this turn
+        try:
+            for _ in range(self.settings.max_turns):
+                await self._maybe_compact(messages, sink)
+                try:
+                    response = await self._stream_once(self._view(messages), sink)
+                except AgentError as exc:
+                    # The prompt no longer fits: compact harder and try once more.
+                    if not _OVERFLOW.search(str(exc)) or not await self._maybe_compact(
+                        messages, sink, force=True
+                    ):
+                        raise
+                    response = await self._stream_once(self._view(messages), sink)
+                messages.append(
+                    {"role": "assistant", "content": [b.to_dict() for b in response.content]}
+                )
+                turn_usage.add(response.usage)
+                self.usage.add(response.usage, _model_of(response, self.escalated or self.route))
+                await _emit(sink, "usage", turn_usage.to_dict())
+                stop_reason = response.stop_reason
+                if checkpoint:
+                    checkpoint(messages)
+                if stop_reason == "pause_turn":
+                    continue
+                if stop_reason == "refusal":
+                    details = getattr(response, "stop_details", None)
+                    refusal = {
+                        "category": getattr(details, "category", None),
+                        "explanation": getattr(details, "explanation", None),
+                    }
+                    await _emit(
+                        sink,
+                        "error",
+                        f"The model declined this request ({refusal['category'] or 'policy'}).",
+                    )
+                    break
+                text = "".join(b.text for b in response.content if b.type == "text")
+                if text:
+                    final_text = [text]
+                tool_uses = [b for b in response.content if b.type == "tool_use"]
+                if not tool_uses:
+                    break
+                tool_calls += len(tool_uses)
+                if stop_reason == "max_tokens":
+                    results = [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": b.id,
+                            "is_error": True,
+                            "content": "Not run: the output hit max_tokens and this tool input was cut off. "
+                            "Split the change into smaller steps.",
+                        }
+                        for b in tool_uses
+                    ]
+                else:
+                    results = await self._run_tools(tool_uses, sink)
+                    for result in results:
+                        failures = failures + 1 if result.get("is_error") else 0
+                    await self._maybe_escalate(failures, sink)
+                    for block in tool_uses:
+                        if block.name == "write_todos" and isinstance(block.input, dict):
+                            self.todos = list(block.input.get("todos") or [])
+                messages.append({"role": "user", "content": results})
+                if checkpoint:
+                    checkpoint(messages)
+            else:
+                await _emit(sink, "status", f"stopped after {self.settings.max_turns} model calls")
+        except (asyncio.CancelledError, KeyboardInterrupt):
+            _close_dangling_tool_uses(messages)
+            if checkpoint:
+                checkpoint(messages)
+            raise
+        result = TurnResult(
+            "\n".join(final_text).strip(),
+            stop_reason,
+            turn_usage,
+            tool_calls,
+            refusal,
+            len(messages) - start,
+        )
+        await _emit(sink, "done", {"stop_reason": stop_reason, "usage": turn_usage.to_dict()})
+        return result
+
+    def _plan(self, block: Any) -> CallPlan:
+        planner = getattr(self.executor, "plan", None)
+        if planner is not None and isinstance(block.input, dict):
+            return planner(block.name, block.input)
+        return CallPlan(READ) if self.executor.parallel_safe(block.name) else CallPlan(EXCLUSIVE)
+
+    async def _maybe_escalate(self, failures: int, sink: EventSink | None) -> None:
+        """After repeated tool failures, run the rest of the turn on the escalate role."""
+        from traceforge import routing
+
+        if self.escalated is not None or failures < routing.ESCALATE_AFTER:
+            return
+        if self.route.role not in {"main", "general"}:
+            return
+        if self.settings.model_explicit and "escalate" not in (self.settings.routes or {}):
+            return  # the user chose the model; do not switch it behind their back
+        target = routing.route(self.settings, "escalate")
+        if target.model == self.route.model and target.effort == self.route.effort:
+            return
+        self.escalated = target
+        await _emit(
+            sink,
+            "status",
+            f"{failures} tool calls failed in a row; switching to {target.model} "
+            f"({target.effort} effort) for the rest of this task",
+        )
+
+    async def _run_tools(
+        self, tool_uses: list[Any], sink: EventSink | None
+    ) -> list[dict[str, Any]]:
+        async def one(block: Any) -> dict[str, Any]:
+            arguments = block.input if isinstance(block.input, dict) else {}
+            await _emit(sink, "tool_call", {"id": block.id, "name": block.name, "input": arguments})
+            if not isinstance(block.input, dict):
+                content, is_error = json.dumps({"INVALID_JSON": str(block.input)[:2000]}), True
+            else:
+                content, is_error = await self.executor.execute(block.name, arguments, block.id)
+            await _emit(
+                sink,
+                "tool_result",
+                {
+                    "id": block.id,
+                    "name": block.name,
+                    "content": content_text(content),
+                    "is_error": is_error,
+                },
+            )
+            if not is_error and block.name == "write_todos":
+                await _emit(sink, "todos", arguments.get("todos", []))
+            result: dict[str, Any] = {
+                "type": "tool_result",
+                "tool_use_id": block.id,
+                "content": content,
+            }
+            if is_error:
+                result["is_error"] = True
+            return result
+
+        plans = [self._plan(b) for b in tool_uses]
+        return await run_batch(tool_uses, plans, one)
+
+
+def content_text(content: Any) -> str:
+    """The text of a tool result (images are counted, not shown)."""
+    if isinstance(content, str):
+        return content
+    texts, images = [], 0
+    for block in content or []:
+        if isinstance(block, dict) and block.get("type") == "text":
+            texts.append(str(block.get("text", "")))
+        elif isinstance(block, dict) and block.get("type") == "image":
+            images += 1
+    if images:
+        texts.append(f"[{images} image{'s' if images != 1 else ''}]")
+    return "\n".join(texts)
+
+
+def _close_dangling_tool_uses(messages: list[dict[str, Any]]) -> None:
+    """After an interruption, answer any unanswered tool_use so the history stays valid."""
+    if not messages or messages[-1]["role"] != "assistant":
+        return
+    pending = [
+        b["id"]
+        for b in messages[-1]["content"]
+        if isinstance(b, dict) and b.get("type") == "tool_use"
+    ]
+    if pending:
+        messages.append(
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": tid,
+                        "is_error": True,
+                        "content": "interrupted by the user",
+                    }
+                    for tid in pending
+                ],
+            }
+        )

traceforge/altium/__init__.py

@@ -0,0 +1,6 @@
+"""Read Altium Designer and CircuitMaker projects (``.PrjPcb``, ``.SchDoc``, ``.PcbDoc``)."""
+
+from traceforge.altium.cfb import AltiumError
+from traceforge.altium.project import AltiumProject, find_projects, load_project
+
+__all__ = ["AltiumError", "AltiumProject", "find_projects", "load_project"]