agent-aimee 0.1.0__py3-none-any.whl

agent_aimee-0.1.0.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: agent-aimee
+Version: 0.1.0
+Summary: A very minimal LLM agent loop with tools and skills
+Project-URL: Homepage, https://github.com/Fortyseven/AgentAImee
+Project-URL: Source Code, https://github.com/Fortyseven/AgentAImee
+Project-URL: Issues, https://github.com/Fortyseven/AgentAImee/issues
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# AgentAImee
+
+A very minimal LLM agent loop for Python, with tools and skills. One runtime
+dependency (`httpx`). Drop it into an existing project; you own the config,
+the tools, and the behavior. Aimee gives you the loop, the OpenAI-compatible
+client, skill discovery, AGENTS.md support, and callback hooks.
+
+- **Model**: any OpenAI-compatible `chat/completions` endpoint via
+  `OPENAI_API_BASE` + `OPENAI_API_KEY` (no `openai` package).
+- **Tools**: built-in `read`, `write`, `edit`, `bash` — **all opt-in** — plus
+  your own tools.
+- **Skills**: `SKILL.md` directories; a catalog is injected into the system
+  prompt and the agent reads the full skill on demand.
+- **Hooks**: extend the run with callbacks — stream tokens, approve/modify
+  tool calls, observe turns, handle errors.
+- **Sync or async**: `agent.run(task)` works in any script; `await
+  agent.run_async(task)` for async code.
+
+## Install
+
+```bash
+uv add agent-aimee        # or: pip install agent-aimee
+```
+
+```python
+from aimee import Aimee, AimeeConfig  # module name is `aimee`
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q          # test suite (no network needed)
+```
+
+## Quickstart
+
+```bash
+export OPENAI_API_BASE=https://api.openai.com/v1   # or any compatible gateway
+export OPENAI_API_KEY=sk-...
+uv run python examples/basic.py "your task here"   # or --repl
+```
+
+The example wires everything up: multi-root workspace, a skills directory,
+AGENTS.md, three basic tools, and console hooks.
+
+## Usage
+
+```python
+from pathlib import Path
+from aimee import Aimee, AimeeConfig
+from aimee.tools import basic_tools
+
+config = AimeeConfig(
+    roots=[Path.cwd(), Path.home() / ".myapp"],  # workspace roots (first = primary)
+    skills_dirs=[Path.home() / ".myapp" / "skills"],
+    model="gpt-4o-mini",  # default: "default"
+)
+agent = Aimee(config, tools=basic_tools())  # read, write, edit, bash
+# agent = Aimee(config, tools=[read()])          # or just the tools you want
+
+report = agent.run("Summarize AGENTS.md")  # sync (also safe inside a running loop)
+# report = await agent.run_async("...")          # async
+
+print(report.final_text, report.turns, report.tool_calls, report.usage)
+```
+
+`RunReport` fields: `final_text`, `turns`, `tool_calls`, `usage` (tokens,
+when the provider reports them), `truncated` (max turns hit), `messages`
+(full transcript).
+
+## Sessions (multi-turn memory)
+
+`agent.run(task)` is stateless — every run starts fresh. For a conversation
+that remembers, create a session:
+
+```python
+session = agent.session()
+session.run("hello, who am I talking to?")
+session.run("what did I just ask?")  # the model sees the whole prior exchange
+
+session.history  # snapshot: [system, user, assistant, user, assistant, ...]
+session.clear()  # start over (a fresh system prompt is built on the next run)
+```
+
+- A session is bound to one agent (sharing its tools/hooks/config); one agent
+  can hold many independent sessions at once.
+- `session.run()` / `await session.run_async()` mirror `Aimee.run()` /
+  `run_async()` — same hooks fire, same `RunReport` comes back (with `messages`
+  being the full session history).
+- Tool calls and their results are part of the history too, so the model can
+  reference earlier tool output in later turns.
+- History is unbounded by design: long conversations will eventually hit the
+  model's context limit — `session.clear()` resets when that gets close.
+  (`history` returns a snapshot; subclass or wrap the session for custom
+  trimming strategies.)
+
+## Configuration (`AimeeConfig`)
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `roots` | `[Path.cwd()]` | Workspace roots, in priority order (see below). All paths are configurable here. |
+| `model` | `"default"` | Model name passed to the endpoint. |
+| `api_base` | `$OPENAI_API_BASE` → `https://api.openai.com/v1` | Endpoint base URL. |
+| `api_key` | `$OPENAI_API_KEY` | Bearer token. |
+| `system_prompt` | built-in minimal prompt | Replaces the base prompt. |
+| `agents_md` | nearest `AGENTS.md` walking up from `roots` | Explicit AGENTS.md path. |
+| `skills_dirs` | `[]` | Directories containing `SKILL.md` skill folders. |
+| `max_turns` | `30` | Model-call budget per run. |
+| `temperature` / `max_tokens` | `None` | Passed through when set. |
+| `bash_timeout` | `120` | Default shell timeout (seconds). |
+| `output_limit` | `100_000` | Tool output truncation (chars). |
+
+**Multi-root rules.** `roots[0]` is the primary root. `read`/`edit` resolve
+relative paths against roots in order (first existing file wins); `write`
+updates the first root that contains the file, and creates new files under
+the primary root; `bash` runs with the primary root as cwd; AGENTS.md
+discovery walks up from each root in order until one is found.
+
+## Tools
+
+Tools are OpenAI function-calling specs plus a handler:
+
+```python
+from aimee import Tool
+
+Tool(
+    name="current_time",
+    description="Get the current local date and time (ISO format).",
+    parameters={"type": "object", "properties": {}},  # JSON Schema
+    handler=lambda args, ctx: "...",  # sync or async; returns str
+)
+agent.add_tool(tool)
+```
+
+`ctx` is a `ToolContext` giving handlers the same workspace view as the
+built-ins: `ctx.roots`, `ctx.resolve(path, must_exist=...)`,
+`ctx.config.bash_timeout`, `ctx.config.output_limit`.
+
+Built-ins (opt-in): `basic_tools()` → all four, `basic_tools(["read", "edit"])`
+→ a subset, or import individually: `from aimee.tools import read, write, edit, bash`.
+
+| Tool | Behavior |
+| --- | --- |
+| `read(path, offset?, limit?)` | Numbered lines (paged), or directory listing. |
+| `write(path, content)` | Create/overwrite; parent dirs created. |
+| `edit(path, old_text, new_text)` | Exact-string replace; `old_text` must match exactly once. |
+| `bash(command, timeout?)` | Shell in the primary root; `[exit N]` + combined output, truncated. |
+
+> **Security note.** `bash` has no built-in approval. The `on_tool_call` hook
+> is the safety mechanism — see `examples/custom_tool.py` for a hook that
+> denies commands containing `rm `. Don't enable `bash` without one.
+
+## Hooks
+
+Register any object defining any subset of these methods (sync or async),
+via `Aimee(..., hooks=[...])` or `agent.add_hook(obj)`:
+
+| Hook | Purpose |
+| --- | --- |
+| `on_delta(chunk: str)` | One streamed chunk of assistant text (streaming on by default). |
+| `on_tool_call(name, args) -> ToolDecision \| None` | Approval gate. `None` = allow; `ToolDecision.deny(reason)` blocks (reason goes to the model); `ToolDecision.modify(new_args)` replaces args. First non-None decision wins. |
+| `on_tool_result(name, args, result)` | After a tool finished (including denials/errors). |
+| `on_turn(turn, response)` | After each completed model response. |
+| `on_error(error)` | Tool errors (run continues, error text goes to the model) and API errors (run aborts). |
+| `on_done(report)` | Once, when the run finishes. |
+
+## Skills
+
+A skill is a directory with a `SKILL.md`:
+
+```
+myapp/skills/
+└── pdf-extract/
+    └── SKILL.md
+```
+
+```markdown
+---
+name: pdf-extract
+description: Extract text from PDF files. Use when the task involves PDFs.
+---
+Full instructions here. The agent reads this file (via the read tool)
+before using the skill.
+```
+
+Set `skills_dirs=[...]`; Aimee injects only the catalog (name, description,
+path) into the system prompt, so skills cost almost nothing until used.
+Frontmatter is parsed minimally (flat `key: value`, no PyYAML).
+
+## AGENTS.md
+
+If `agents_md` is unset, Aimee finds the nearest `AGENTS.md` walking up from
+each root (in root order) and includes it under a "Project instructions"
+heading. Give an explicit path to override.
+
+## Tests
+
+```bash
+uv run pytest -q
+```
+
+The suite is fully offline: the HTTP client is tested against
+`httpx.MockTransport`, and the agent loop against a scripted fake model.
+
+## Project layout
+
+```
+src/aimee/
+  agent.py    # the loop + Aimee facade (sync/async)
+  client.py   # OpenAI-compatible client (chat + SSE streaming)
+  config.py   # AimeeConfig
+  hooks.py    # hook dispatch (sync/async)
+  prompt.py   # system prompt assembly (base + AGENTS.md + skills)
+  skills.py   # SKILL.md discovery + catalog
+  types.py    # messages, responses, reports
+  tools/      # base primitives + built-in read/write/edit/bash
+examples/     # basic.py, custom_tool.py + workspace fixtures
+tests/        # offline test suite
+```

agent_aimee-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+aimee/__init__.py,sha256=ZtclDBHRGGGnoECef8e8xKy3XZDUTL3T_j43fZCiVw0,832
+aimee/agent.py,sha256=nAnt45Je66mGBgBF66UtJYFiHib57Kifb3KB-la1rYw,14609
+aimee/client.py,sha256=Hbvs4sYvlOcbGoJkWNoCwe43ouPYjJKxXYGZhG6fl_I,7047
+aimee/config.py,sha256=dzTnM9fOY3kCJ3tzBxP5AvjWNJlTl2iyOnNdTW3mnxo,2060
+aimee/hooks.py,sha256=BXgBnO62J24SU7_qABhAsP821e0Fwt9n5KXe3L9k9c8,1692
+aimee/prompt.py,sha256=N7ndgD7UNR5DJd1tAn6nKtg8d6ZtiieXXulIR8lU1yw,1809
+aimee/skills.py,sha256=yW8P5ioTEX0l8eeMNVtrbw00aBNk6AiEn9Mpm9nk99g,2996
+aimee/types.py,sha256=_fXETvcVA3NBi00BHXt1B3kLA4cQJMM2KM8PsrmD3kY,4813
+aimee/tools/__init__.py,sha256=qAard2VHkbfrUpuhHkPSEvIBHVlKQAOWmfMTVS_SCM0,1356
+aimee/tools/base.py,sha256=GYZeXz43HUv8EORJ0aqjZYb5YfVTr7YpcquapYSawtw,2500
+aimee/tools/bash.py,sha256=50fGNHFJYSTMX1YSo6ixhWXY5Wb6Bip-80QdDFNdlno,1741
+aimee/tools/fs.py,sha256=ILSeC1l9uX5XicgJWqGZxm5rbqqRgJEIR8fJ-ad7dUs,4680
+agent_aimee-0.1.0.dist-info/METADATA,sha256=q6qgyDrqRnf69KQFUCBKWkKe1gCI3bKlpuJDvkfo68g,9202
+agent_aimee-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+agent_aimee-0.1.0.dist-info/RECORD,,

agent_aimee-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

aimee/__init__.py

@@ -0,0 +1,41 @@
+"""Aimee: a very minimal LLM agent loop with tools and skills."""
+
+from aimee.agent import Aimee, AimeeSession
+from aimee.client import OpenAIClient
+from aimee.config import AimeeConfig
+from aimee.skills import Skill, load_skills, parse_frontmatter
+from aimee.tools.base import Tool, ToolContext
+from aimee.types import (
+    AimeeError,
+    ChatResponse,
+    Message,
+    RunReport,
+    StreamDelta,
+    TokenUsage,
+    ToolCall,
+    ToolCallDelta,
+    ToolDecision,
+)
+
+__all__ = [
+    "Aimee",
+    "AimeeConfig",
+    "AimeeError",
+    "AimeeSession",
+    "ChatResponse",
+    "Message",
+    "OpenAIClient",
+    "RunReport",
+    "Skill",
+    "StreamDelta",
+    "TokenUsage",
+    "Tool",
+    "ToolCall",
+    "ToolCallDelta",
+    "ToolContext",
+    "ToolDecision",
+    "load_skills",
+    "parse_frontmatter",
+]
+
+__version__ = "0.1.0"

aimee/agent.py

@@ -0,0 +1,381 @@
+"""The agent loop and the Aimee facade (sync + async entry points)."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import threading
+from collections.abc import Iterable
+from typing import Any
+
+from aimee.client import OpenAIClient
+from aimee.config import AimeeConfig
+from aimee.hooks import call_hook, fire
+from aimee.prompt import build_system_prompt
+from aimee.skills import load_skills
+from aimee.tools.base import Tool, ToolContext, validate_tools
+from aimee.types import (
+    ROLE_SYSTEM,
+    AimeeError,
+    ChatResponse,
+    Message,
+    RunReport,
+    TokenUsage,
+    ToolCall,
+    ToolDecision,
+)
+
+_MAX_TURN_NOTE = "Stopped: max turns reached."
+
+
+class Aimee:
+    """A minimal LLM agent: model + tools + skills + callback hooks.
+
+    Sync usage (works in any script, even inside a running event loop)::
+
+        agent = Aimee(config, tools=basic_tools())
+        report = agent.run("Summarize AGENTS.md")
+
+    Async usage::
+
+        report = await Aimee(config, tools=basic_tools()).run_async("...")
+
+    `client` accepts anything with `chat()`/`stream_chat()` (dependency
+    injection for tests); otherwise an OpenAIClient is created lazily and
+    reused across runs. Release resources with `close()`/`aclose()` or by
+    using the agent as a context manager.
+    """
+
+    def __init__(
+        self,
+        config: AimeeConfig | None = None,
+        *,
+        client: Any = None,
+        tools: Iterable[Tool] = (),
+        hooks: Iterable[Any] = (),
+        stream: bool = True,
+    ):
+        self.config = config or AimeeConfig()
+        self._client = client
+        self._owns_client = client is None
+        self._client_closed = False
+        self._loop_thread: _LoopThread | None = None
+        self.tools: list[Tool] = list(tools)
+        self.hooks: list[Any] = list(hooks)
+        self.stream = stream
+
+    # -- registration ------------------------------------------------------
+
+    def add_tool(self, tool: Tool) -> Aimee:
+        """Register one tool; returns self for chaining."""
+        self.tools.append(tool)
+        return self
+
+    def add_hook(self, hook: Any) -> Aimee:
+        """Register a hook object (any subset of the on_* methods); chainable."""
+        self.hooks.append(hook)
+        return self
+
+    # -- entry points ------------------------------------------------------
+
+    def run(self, task: str) -> RunReport:
+        """Run the agent (stateless: no memory between runs). Sync; see run_async."""
+        return self._sync_submit(self.run_async(task))
+
+    async def run_async(self, task: str) -> RunReport:
+        """Run the agent (stateless: no memory between runs). Async."""
+        await self._ensure_client()
+        return await self._run(task)
+
+    def session(self) -> AimeeSession:
+        """Start a conversation session that keeps chat history across runs."""
+        return AimeeSession(self)
+
+    def _sync_submit(self, coro: Any) -> Any:
+        """Run a coroutine on the agent's persistent background event loop."""
+        if self._loop_thread is None:
+            self._loop_thread = _LoopThread()
+        return self._loop_thread.submit(coro)
+
+    async def _run_with_history(self, task: str, history: list[Message]) -> RunReport:
+        """One run whose messages accumulate in `history` (session support)."""
+        await self._ensure_client()
+        return await self._run(task, history=history)
+
+    async def _ensure_client(self) -> None:
+        """Create the managed model client on first use, or again after aclose()."""
+        if self._client is None or (self._owns_client and self._client_closed):
+            self._client = OpenAIClient(self.config)
+            self._owns_client = True
+            self._client_closed = False
+
+    async def aclose(self) -> None:
+        """Close the model client Aimee created itself (no-op for injected clients)."""
+        if self._owns_client and self._client is not None and not self._client_closed:
+            await self._client.aclose()
+            self._client_closed = True
+        self.close()
+
+    def close(self) -> None:
+        """Stop the sync background loop; close an owned client while the loop is up."""
+        loop_thread = self._loop_thread
+        self._loop_thread = None
+        if loop_thread is None:
+            return
+        if self._owns_client and self._client is not None and not self._client_closed:
+            loop_thread.submit(self._client.aclose())
+            self._client_closed = True
+        loop_thread.stop()
+
+    async def __aenter__(self) -> Aimee:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    # -- the loop ----------------------------------------------------------
+
+    async def _run(self, task: str, history: list[Message] | None = None) -> RunReport:
+        tools = validate_tools(self.tools)
+        ctx = ToolContext(config=self.config, roots=self.config.resolved_roots())
+        skills = load_skills(self.config.skills_dirs) if self.config.skills_dirs else []
+        if history is None:
+            messages: list[Message] = [
+                Message.system(build_system_prompt(self.config, skills)),
+                Message.user(task),
+            ]
+        else:
+            # Session mode: append this turn onto the accumulated conversation.
+            if not history or history[0].role != ROLE_SYSTEM:
+                history.insert(0, Message.system(build_system_prompt(self.config, skills)))
+            history.append(Message.user(task))
+            messages = history
+        usage = TokenUsage()
+        tool_call_count = 0
+        turns = 0
+        truncated = False
+        final_text = ""
+
+        try:
+            while True:
+                if turns >= self.config.max_turns:
+                    truncated = True
+                    break
+                turns += 1
+                response = await self._request_turn(messages, tools)
+                if response.usage:
+                    usage.add(response.usage)
+                await fire(self.hooks, "on_turn", turns, response)
+
+                if not response.has_tool_calls:
+                    messages.append(Message.assistant(response.content or ""))
+                    final_text = response.content
+                    break
+
+                messages.append(_assistant_message(response))
+                for tool_call in response.tool_calls:
+                    tool_call_count += 1
+                    result, args_used = await self._dispatch_tool(tool_call, tools, ctx)
+                    await fire(self.hooks, "on_tool_result", tool_call.name, args_used, result)
+                    messages.append(Message.tool_result(tool_call.id, result))
+        except AimeeError as e:
+            await fire(self.hooks, "on_error", e)
+            raise
+
+        report = RunReport(
+            final_text=final_text or (_MAX_TURN_NOTE if truncated else ""),
+            turns=turns,
+            tool_calls=tool_call_count,
+            usage=usage,
+            truncated=truncated,
+            messages=messages,
+        )
+        await fire(self.hooks, "on_done", report)
+        return report
+
+    async def _request_turn(self, messages: list[Message], tools: dict[str, Tool]) -> ChatResponse:
+        """One model request; streams deltas to on_delta hooks when enabled."""
+        tool_list = list(tools.values()) if tools else None
+        if not self.stream:
+            return await self._client.chat(messages, tools=tool_list)
+
+        content_parts: list[str] = []
+        slots: dict[int, dict[str, str]] = {}
+        finish_reason: str | None = None
+        usage: TokenUsage | None = None
+        async for delta in self._client.stream_chat(messages, tools=tool_list):
+            if delta.content:
+                content_parts.append(delta.content)
+                await fire(self.hooks, "on_delta", delta.content)
+            for tc in delta.tool_calls:
+                slot = slots.setdefault(tc.index, {"id": "", "name": "", "args": ""})
+                if tc.id:
+                    slot["id"] = tc.id
+                if tc.name:
+                    slot["name"] = tc.name
+                slot["args"] += tc.arguments
+            if delta.finish_reason:
+                finish_reason = delta.finish_reason
+            if delta.usage:
+                usage = usage or TokenUsage()
+                usage.add(delta.usage)
+
+        tool_calls = [_assemble_tool_call(idx, slot) for idx, slot in sorted(slots.items())]
+        return ChatResponse(
+            content="".join(content_parts),
+            tool_calls=tool_calls,
+            usage=usage,
+            finish_reason=finish_reason,
+        )
+
+    async def _dispatch_tool(
+        self, tool_call: ToolCall, tools: dict[str, Tool], ctx: ToolContext
+    ) -> tuple[str, dict[str, Any]]:
+        """Apply the approval hook, execute the tool, and report the outcome."""
+        decision = await self._decide(tool_call.name, tool_call.arguments)
+        if decision is not None and not decision.allowed:
+            return f"Denied by client: {decision.reason or 'no reason given'}", tool_call.arguments
+        args = (
+            decision.args
+            if decision is not None and decision.args is not None
+            else tool_call.arguments
+        )
+        tool = tools.get(tool_call.name)
+        if tool is None:
+            result = f"Error: unknown tool: {tool_call.name!r}"
+        else:
+            result = await self._execute_tool(tool, args, ctx)
+        return result, args
+
+    async def _decide(self, name: str, args: dict[str, Any]) -> ToolDecision | None:
+        """First non-None ToolDecision from the hooks wins; None means allow."""
+        for hook in self.hooks:
+            decision = await call_hook(hook, "on_tool_call", name, args)
+            if decision is not None:
+                return decision
+        return None
+
+    async def _execute_tool(self, tool: Tool, args: dict[str, Any], ctx: ToolContext) -> str:
+        """Run a tool handler; errors become model-visible text + on_error."""
+        try:
+            result = tool.handler(args, ctx)
+            if inspect.isawaitable(result):
+                result = await result
+            return result if isinstance(result, str) else str(result)
+        except Exception as e:
+            await fire(self.hooks, "on_error", e)
+            return f"Error: {type(e).__name__}: {e}"
+
+
+class AimeeSession:
+    """A multi-turn conversation on one agent; chat history persists across runs.
+
+    Unlike `Aimee.run()` (stateless), each `run()` here appends to a shared
+    history, so the model sees the whole prior conversation::
+
+        session = agent.session()
+        session.run("hello")
+        session.run("and now...")   # the model remembers the first turn
+
+    A session is bound to one agent (sharing its tools/hooks/config), but an
+    agent can hold many independent sessions at once.
+    """
+
+    def __init__(self, agent: Aimee) -> None:
+        self._agent = agent
+        self._history: list[Message] = []
+
+    @property
+    def history(self) -> list[Message]:
+        """A snapshot of the conversation so far (system message first)."""
+        return list(self._history)
+
+    def run(self, task: str) -> RunReport:
+        """Run one turn of the conversation (sync)."""
+        return self._agent._sync_submit(self.run_async(task))
+
+    async def run_async(self, task: str) -> RunReport:
+        """Run one turn of the conversation (async)."""
+        return await self._agent._run_with_history(task, self._history)
+
+    def clear(self) -> None:
+        """Forget the conversation; a fresh system prompt is built next run."""
+        self._history.clear()
+
+
+def _assistant_message(response: ChatResponse) -> Message:
+    """Assistant message in OpenAI wire form (content + raw tool calls)."""
+    tool_calls = [
+        {
+            "id": tc.id,
+            "type": "function",
+            "function": {
+                "name": tc.name,
+                "arguments": tc.raw_arguments or json.dumps(tc.arguments),
+            },
+        }
+        for tc in response.tool_calls
+    ]
+    return Message.assistant(response.content or "", tool_calls)
+
+
+def _assemble_tool_call(index: int, slot: dict[str, str]) -> ToolCall:
+    """Join streamed argument fragments and parse the final JSON object."""
+    raw = slot["args"]
+    try:
+        args = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError as e:
+        raise AimeeError(f"Model returned invalid JSON tool arguments: {raw!r}") from e
+    if not isinstance(args, dict):
+        raise AimeeError(f"Model returned non-object tool arguments: {raw!r}")
+    return ToolCall(id=slot["id"], name=slot["name"], arguments=args, raw_arguments=raw)
+
+
+class _LoopThread:
+    """Persistent background event-loop thread for the sync API.
+
+    All `Aimee.run()` calls share one loop, so the owned HTTP client stays
+    on a single event loop (httpx clients are not reusable across loops).
+    Works even when the caller has a running event loop (Jupyter, async
+    frameworks, Tk). The coroutine's exception, if any, is re-raised.
+    """
+
+    def __init__(self) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._ready = threading.Event()
+
+    def submit(self, coro: Any) -> Any:
+        """Run a coroutine on the background loop; block until it finishes."""
+        if self._loop is None or not self._loop.is_running():
+            self._start()
+        return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+
+    def _start(self) -> None:
+        loop = asyncio.new_event_loop()
+        self._loop = loop
+        self._ready.clear()
+        thread = threading.Thread(
+            target=self._run_loop, args=(loop,), name="aimee-loop", daemon=True
+        )
+        self._thread = thread
+        thread.start()
+        if not self._ready.wait(timeout=10):
+            raise AimeeError("Aimee background event loop failed to start")
+
+    def _run_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        asyncio.set_event_loop(loop)
+        loop.call_soon(self._ready.set)
+        loop.run_forever()
+
+    def stop(self) -> None:
+        """Stop the loop and its thread; safe to call more than once."""
+        if self._loop is not None and self._loop.is_running():
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            if self._thread is not None:
+                self._thread.join(timeout=5)
+        if self._loop is not None:
+            self._loop.close()
+        self._loop = None
+        self._thread = None