aon-agent 1.0.0__py3-none-any.whl

aon/__init__.py

@@ -0,0 +1,2 @@
+"""AON, a self-hosted AI agent."""
+__version__ = "1.0.0"

aon/approval_gate.py

@@ -0,0 +1,48 @@
+# GUARDRAIL MODULE -- not editable by agent tools (see config.GUARDRAIL_PATHS).
+from __future__ import annotations
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+@dataclass
+class PendingAction:
+    tool: str
+    args: dict
+
+@dataclass
+class Decision:
+    approved: bool
+    edited_args: dict | None = None
+    reason: str = ""
+
+class ApprovalGate(ABC):
+    @abstractmethod
+    async def request(self, action: PendingAction) -> Decision: ...
+
+class AutoGate(ApprovalGate):
+    def __init__(self, approve: bool = True):
+        self._approve = approve
+    async def request(self, action: PendingAction) -> Decision:
+        return Decision(approved=self._approve, reason="auto")
+
+class QueueGate(ApprovalGate):
+    def __init__(self, on_pending=None):
+        self._next = 1
+        self._pending: dict[int, tuple[PendingAction, asyncio.Future]] = {}
+        self._on_pending = on_pending
+    async def request(self, action: PendingAction) -> Decision:
+        rid = self._next; self._next += 1
+        fut = asyncio.get_running_loop().create_future()
+        self._pending[rid] = (action, fut)
+        if self._on_pending is not None:
+            await self._on_pending(rid, action)
+        try:
+            return await fut
+        finally:
+            self._pending.pop(rid, None)
+    def pending(self) -> list[tuple[int, PendingAction]]:
+        return [(rid, pa) for rid, (pa, _f) in self._pending.items()]
+    def resolve(self, req_id: int, decision: Decision) -> None:
+        entry = self._pending.get(req_id)
+        if entry and not entry[1].done():
+            entry[1].set_result(decision)

aon/attachments.py

@@ -0,0 +1,132 @@
+"""Files and photos attached to a chat goal: saved into the workspace, described to the agent,
+and (for vision models) sent to the model as images."""
+import base64, binascii, mimetypes, re, time
+from dataclasses import dataclass
+from pathlib import Path
+import httpx
+
+MAX_FILES = 10
+MAX_FILE_BYTES = 20 * 1024 * 1024
+MAX_TOTAL_BYTES = 40 * 1024 * 1024
+INLINE_TEXT_BYTES = 32 * 1024
+
+_IMAGE_EXT = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+              ".gif": "image/gif", ".webp": "image/webp", ".bmp": "image/bmp"}
+
+
+class AttachmentError(ValueError):
+    pass
+
+
+@dataclass
+class Attachment:
+    name: str
+    path: Path
+    mime: str
+    size: int
+    is_image: bool
+
+
+def _safe_name(name: str) -> str:
+    base = re.split(r"[\\/]", name or "")[-1]
+    base = re.sub(r"[^A-Za-z0-9._ -]", "_", base).strip(" .")
+    return base[:120] or "file"
+
+
+def _mime(name: str, given: str) -> str:
+    ext = Path(name).suffix.lower()
+    if ext in _IMAGE_EXT:
+        return _IMAGE_EXT[ext]
+    return given or mimetypes.guess_type(name)[0] or "application/octet-stream"
+
+
+def save_attachments(items: list[dict], workdir) -> list[Attachment]:
+    """Decode and validate everything first, then write; a bad item saves nothing."""
+    items = items or []
+    if len(items) > MAX_FILES:
+        raise AttachmentError(f"too many attachments ({len(items)}); the limit is {MAX_FILES}")
+    decoded, total = [], 0
+    for it in items:
+        name = _safe_name(str(it.get("name", "")))
+        try:
+            data = base64.b64decode(it.get("data") or "", validate=True)
+        except (binascii.Error, ValueError):
+            raise AttachmentError(f"attachment {name!r} is not valid base64")
+        if len(data) > MAX_FILE_BYTES:
+            raise AttachmentError(f"attachment {name!r} is larger than {MAX_FILE_BYTES // (1024 * 1024)} MB")
+        total += len(data)
+        if total > MAX_TOTAL_BYTES:
+            raise AttachmentError(f"attachments are larger than {MAX_TOTAL_BYTES // (1024 * 1024)} MB in total")
+        decoded.append((name, str(it.get("type") or ""), data))
+    out = []
+    if not decoded:
+        return out
+    up = Path(workdir) / "uploads"
+    up.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    for name, given, data in decoded:
+        path = up / f"{stamp}-{name}"
+        n = 1
+        while path.exists():
+            path = up / f"{stamp}-{n}-{name}"; n += 1
+        path.write_bytes(data)
+        mime = _mime(name, given)
+        out.append(Attachment(name, path, mime, len(data), mime.startswith("image/")))
+    return out
+
+
+def _fmt(n: int) -> str:
+    if n < 1024:
+        return f"{n} B"
+    if n < 1024 * 1024:
+        return f"{n / 1024:.1f} KB"
+    return f"{n / (1024 * 1024):.1f} MB"
+
+
+def _inline_text(a: Attachment) -> str | None:
+    if a.is_image or a.size > INLINE_TEXT_BYTES:
+        return None
+    raw = a.path.read_bytes()
+    if b"\x00" in raw:
+        return None
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def attachment_note(atts: list[Attachment], vision: bool = True) -> str:
+    """Text appended to the goal so the agent knows what was attached and where it is."""
+    if not atts:
+        return ""
+    lines = ["[Attached files, saved in the workspace]"]
+    blocks = []
+    for a in atts:
+        desc = f"- {a.name} ({a.mime}, {_fmt(a.size)}) at {a.path}"
+        if a.is_image:
+            desc += " - image is shown to you below" if vision else \
+                " - image; the current model cannot see images, only the file path"
+        lines.append(desc)
+        text = _inline_text(a)
+        if text is not None:
+            blocks.append(f"--- {a.name} ---\n{text}\n--- end of {a.name} ---")
+    return "\n".join(lines + blocks)
+
+
+def image_parts(atts: list[Attachment]) -> list[dict]:
+    """OpenAI-style image content parts (Ollama's /v1 endpoint accepts data URLs)."""
+    return [{"type": "image_url",
+             "image_url": {"url": f"data:{a.mime};base64," + base64.b64encode(a.path.read_bytes()).decode()}}
+            for a in atts if a.is_image]
+
+
+async def supports_vision(base_url: str, model: str) -> bool:
+    root = re.sub(r"/v1/?$", "", base_url.rstrip("/"))
+    try:
+        async with httpx.AsyncClient(timeout=15) as c:
+            r = await c.post(f"{root}/api/show", json={"model": model})
+            if r.status_code != 200:
+                return False
+            return "vision" in (r.json().get("capabilities") or [])
+    except (httpx.HTTPError, ValueError):
+        return False

aon/audit.py

@@ -0,0 +1,10 @@
+from aon.persistence import Database
+
+def make_audit_hook(db: Database, session_id: int, decisions: dict):
+    async def hook(event: dict):
+        if event.get("type") != "step":
+            return
+        db.add_action(session_id, event.get("tool", ""), "",
+                      "approved" if event.get("approved") else "rejected",
+                      "", event.get("output", ""), "", 0)
+    return hook

aon/backends.py

@@ -0,0 +1,42 @@
+"""Which backend serves a chat request.
+
+AON can keep one chat model on a separate backend (vLLM, for real multi-user serving) while
+everything else - the embedder and the model-management tools - stays on Ollama. The chat model
+is named by cfg.chat_model; requests for it (or for the default when it is the chat model) go to
+cfg.chat_base_url with the chat sampling settings. Any other model stays on Ollama. With
+cfg.chat_model blank, nothing changes: all chat is on Ollama as before.
+"""
+from __future__ import annotations
+
+
+def model_is_chat(cfg, model) -> bool:
+    """True when this request should go to the separate chat backend."""
+    if not cfg.chat_model:
+        return False
+    return (model or cfg.default_model) == cfg.chat_model
+
+
+def chat_base_url(cfg, model=None) -> str:
+    if model_is_chat(cfg, model):
+        return cfg.chat_base_url or cfg.ollama_base_url
+    return cfg.ollama_base_url
+
+
+def chat_sampling(cfg, model=None) -> dict:
+    if not model_is_chat(cfg, model):
+        return {}
+    out = {}
+    if cfg.chat_temperature is not None:
+        out["temperature"] = cfg.chat_temperature
+    if cfg.chat_repetition_penalty is not None:
+        out["repetition_penalty"] = cfg.chat_repetition_penalty
+    if cfg.chat_top_p is not None:
+        out["top_p"] = cfg.chat_top_p
+    return out
+
+
+def make_chat_llm(cfg, model, http=None):
+    from aon.llm_client import LLMClient
+    return LLMClient(chat_base_url(cfg, model), model or cfg.default_model,
+                     http=http, sampling=chat_sampling(cfg, model),
+                     retry_without_thinking=model_is_chat(cfg, model) and bool(cfg.chat_base_url))

aon/build.py

@@ -0,0 +1,111 @@
+from pathlib import Path
+from aon.config import Config
+from aon.llm_client import LLMClient
+from aon.tools.base import ToolRegistry
+from aon.tools.files_read import ReadFileTool, ListDirTool
+from aon.tools.files_write import WriteFileTool, EditFileTool
+from aon.tools.shell import RunCommandTool
+from aon.tools.web import WebFetchTool, WebSearchTool
+from aon.approval_gate import ApprovalGate, AutoGate
+from aon.engine import Agent
+from aon.memory import MemoryStore, RememberTool
+from aon.skills import SkillStore, ReadSkillTool, WriteSkillTool, SkillFilesTool
+from aon.prompts import load_system_prompt
+
+def mem_store(cfg: Config) -> MemoryStore:
+    return MemoryStore(Path("memory") / "episodes.db")
+
+def skill_store(cfg: Config) -> SkillStore:
+    return SkillStore(Path("skills"))
+
+def build_registry(cfg: Config, *, workdir=None, skills_root=None, mem_path=None, include_evals=True, mcp_manager=None, model=None, embedder=None) -> ToolRegistry:
+    wd = workdir or cfg.workdir
+    sk = Path(skills_root) if skills_root else Path("skills")
+    mp = Path(mem_path) if mem_path else (Path("memory") / "episodes.db")
+    r = ToolRegistry()
+    r.register(ReadFileTool(wd))
+    r.register(ListDirTool(wd))
+    r.register(WriteFileTool(wd))
+    r.register(EditFileTool(wd))
+    r.register(RunCommandTool(wd, cfg.command_timeout))
+    r.register(WebFetchTool())
+    r.register(WebSearchTool())
+    from aon.tools.map_tool import ShowMapTool
+    from aon.geo import default_geo
+    r.register(ShowMapTool(default_geo()))
+    ms = MemoryStore(mp); ss = SkillStore(sk)
+    r.register(RememberTool(ms))
+    from aon.memory_extract import SearchMemoryTool, LearnUrlTool
+    r.register(SearchMemoryTool(ms, embedder=embedder))
+    async def _fetch(url):
+        res = await WebFetchTool().run({"url": url})
+        return res.output if res.ok else ""
+    # tools that call the model themselves use the one picked for this chat
+    from aon.backends import make_chat_llm
+    tool_llm = make_chat_llm(cfg, model)
+    r.register(LearnUrlTool(_fetch, tool_llm, ms))
+    from aon.skill_author import DraftSkillTool
+    r.register(DraftSkillTool(_fetch, tool_llm, ss))
+    r.register(ReadSkillTool(ss))
+    r.register(WriteSkillTool(ss))
+    r.register(SkillFilesTool(ss))
+    from aon.capabilities import CapabilitiesTool
+    r.register(CapabilitiesTool(r, ss))
+    if include_evals:
+        from aon.skill_evals import RunSkillEvalsTool
+        r.register(RunSkillEvalsTool(cfg))
+    if mcp_manager is not None:
+        # interactive app only (not the eval sandbox): gated tools that extend AON
+        from aon.install_tools import AddMcpServerTool, ImportSkillsTool
+        r.register(AddMcpServerTool(mcp_manager))
+        r.register(ImportSkillsTool(ss))
+        from aon.model_tools import PullModelTool, ListModelsTool, RemoveModelTool
+        r.register(PullModelTool(cfg.ollama_base_url))
+        r.register(ListModelsTool(cfg.ollama_base_url))
+        r.register(RemoveModelTool(cfg.ollama_base_url))
+        from aon.mcp_tools import McpTool
+        for spec in mcp_manager.tools():
+            r.register(McpTool(mcp_manager, spec))
+    return r
+
+def make_router(cfg, llm, reg, memory=None):
+    from aon.router import deliberate
+    tool_names = {t.name for t in reg.list()}
+    tsum = "\n".join(f"- {t.name}: {((t.description or '').splitlines() or [''])[0][:100]}"
+                     for t in reg.list())
+    async def _router(goal, conversation=None):
+        from aon.router import ensure_map, pending_place_question, Plan
+        from aon.geo import map_hint
+        map_open = any("[map shown]" in (t.get("content") or "") for t in (conversation or [])[-6:])
+        pending = pending_place_question(conversation)
+        hinted = pending or map_hint(goal, map_open)
+        if hinted:
+            # map-like message: the narrow extractor (~2 s) first; if it finds a map request the big
+            # planner (~9 s, and it invented "Melbourne" places in testing) is not needed at all
+            quick = await ensure_map(Plan("", "map", [], False, None, None), goal, llm, conversation, map_open,
+                                     pending_question=pending)
+            if quick.map:
+                return quick
+        ssum = "\n".join(f"- {n}: {d}" for n, d in skill_store(cfg).list())
+        plan = await deliberate(goal, llm, tools_summary=tsum, skills_summary=ssum,
+                                memory_text=(memory or mem_store(cfg)).context_for(goal), valid_tools=tool_names,
+                                conversation=conversation)
+        # the extractor already ran (and found nothing) for hinted messages: don't ask it twice
+        return await ensure_map(plan, goal, llm, conversation, map_open, allow_extract=not hinted)
+    return _router
+
+def build_agent(cfg: Config, gate: ApprovalGate) -> Agent:
+    reg = build_registry(cfg)
+    llm = LLMClient(cfg.ollama_base_url, cfg.default_model)
+    return Agent(llm, reg, gate, max_steps=cfg.max_steps,
+                 memory=mem_store(cfg), skills=skill_store(cfg),
+                 system_prompt=load_system_prompt(Path("system_prompt.txt")),
+                 router=make_router(cfg, llm, reg))
+
+def build_eval_agent(cfg, workspace, skills_dir, model, llm) -> Agent:
+    reg = build_registry(cfg, workdir=workspace, skills_root=skills_dir,
+                         mem_path=Path(workspace) / "_eval_mem.md", include_evals=False)
+    return Agent(llm, reg, AutoGate(approve=True), max_steps=cfg.max_steps,
+                 memory=MemoryStore(Path(workspace) / "_eval_mem.md"),
+                 skills=SkillStore(skills_dir),
+                 system_prompt=load_system_prompt(Path("system_prompt.txt")))

aon/capabilities.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+from aon.tools.base import Tool, ToolResult
+
+
+class CapabilitiesTool(Tool):
+    name = "capabilities"
+    description = "List what AON can do: its tools and its known skills (with any prerequisites)."
+    parameters = {"type": "object", "properties": {}}
+    mutating = False
+
+    def __init__(self, registry, skill_store):
+        self.registry = registry
+        self.skills = skill_store
+
+    async def run(self, args):
+        tools = "\n".join(
+            f"- {t.name}: {((t.description or '').splitlines() or [''])[0][:100]}"
+            for t in self.registry.list() if t.name != self.name)
+        sk = []
+        for n, d in self.skills.list():
+            try:
+                req = self.skills.info(n).get("requires", "")
+            except Exception:
+                req = ""
+            sk.append(f"- {n}: {d}" + (f" (requires: {req})" if req else ""))
+        return ToolResult(ok=True, output=(
+            "My capabilities (tools):\n" + tools +
+            "\n\nMy skills:\n" + ("\n".join(sk) if sk else "(none yet)")))

aon/cli.py

@@ -0,0 +1,147 @@
+"""The `aon` command.
+
+    aon init    create a home folder with a starter config.toml
+    aon serve   run the web UI
+    aon mcp     run AON as an MCP server over stdio (for Claude Desktop, Claude Code, Cursor, ...)
+
+Everything AON keeps (config.toml, chats, memory, documents, skills) lives in one home folder:
+--home, else $AON_HOME, else ~/.aon. AON runs inside that folder, so an existing install such as
+~/app on a server is a valid home as it is.
+"""
+from __future__ import annotations
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+from aon import __version__
+
+DEFAULT_HOME = "~/.aon"
+CONFIG = "config.toml"
+
+CONFIG_TEMPLATE = """\
+# AON configuration: https://github.com/leo007-htun/AON#%EF%B8%8F-configure-configtoml
+ollama_base_url = "{ollama}"     # Ollama's OpenAI-compatible endpoint (chat + embeddings)
+default_model = "{model}"         # a chat model with tool support
+workdir = "{workdir}"
+bind = "{bind}"                   # address:port of the web UI
+always_ask = []
+max_steps = 40
+command_timeout = 120
+embed_model = "nomic-embed-text"
+context_window = 16384           # the chat model's context length
+reply_reserve = 6144
+history_tokens = 5000
+
+# Optional: chat on a vLLM server for several users at once
+# chat_base_url = "http://gpu-box:8001/v1"
+# chat_model = "aon"
+"""
+
+
+def resolve_home(arg: str | None) -> Path:
+    return Path(arg or os.environ.get("AON_HOME") or DEFAULT_HOME).expanduser().resolve()
+
+
+def init_home(home: Path, ollama: str, model: str, bind: str, force: bool = False) -> list[str]:
+    """Create the home folder; existing files are kept unless force. Returns what was written."""
+    home = Path(home)
+    home.mkdir(parents=True, exist_ok=True)
+    created = []
+    for d in ("workspace", "memory", "skills"):
+        (home / d).mkdir(exist_ok=True)
+    cfg = home / CONFIG
+    if force or not cfg.exists():
+        cfg.write_text(CONFIG_TEMPLATE.format(ollama=ollama, model=model, bind=bind,
+                                              workdir=(home / "workspace").as_posix()), encoding="utf-8")
+        created.append(CONFIG)
+    if not (home / "mcp.json").exists():
+        (home / "mcp.json").write_text("[]\n", encoding="utf-8")
+        created.append("mcp.json")
+    bundled = Path(__file__).resolve().parent / "default_skills"
+    for skill in sorted(bundled.iterdir()) if bundled.is_dir() else []:
+        target = home / "skills" / skill.name
+        if skill.is_dir() and not target.exists():
+            shutil.copytree(skill, target)
+            created.append(f"skills/{skill.name}")
+    return created
+
+
+def _enter(home: Path) -> bool:
+    if not (home / CONFIG).exists():
+        print(f"No {CONFIG} in {home}. Create one first:\n  aon init --home {home}", file=sys.stderr)
+        return False
+    os.chdir(home)          # AON's data paths (memory/, skills/, mcp.json, ...) are relative to home
+    return True
+
+
+def _cmd_init(a) -> int:
+    home = resolve_home(a.home)
+    created = init_home(home, a.ollama, a.model, a.bind, force=a.force)
+    print(f"AON home: {home}")
+    for f in created:
+        print(f"  created {f}")
+    if CONFIG not in created:
+        print(f"  kept the existing {CONFIG} (use --force to replace it)")
+    print("\nNext:\n"
+          f"  ollama pull nomic-embed-text && ollama pull {a.model}\n"
+          f"  aon serve{'' if a.home is None else ' --home ' + str(home)}     # web UI on http://{a.bind}\n"
+          f"  aon mcp{'' if a.home is None else ' --home ' + str(home)}       # MCP server (stdio)")
+    return 0
+
+
+def _cmd_serve(a) -> int:
+    home = resolve_home(a.home)
+    if not _enter(home):
+        return 2
+    import uvicorn
+    from aon.config import load_config
+    from aon.main import build_app_from_config
+    cfg = load_config(CONFIG)
+    host, _, port = cfg.bind.partition(":")
+    app = build_app_from_config(CONFIG)
+    # attachments arrive base64-encoded over the websocket (40 MB raw max, ~54 MB encoded)
+    uvicorn.run(app, host=a.host or host or "127.0.0.1", port=a.port or int(port or 8700),
+                ws_max_size=64 * 1024 * 1024)
+    return 0
+
+
+def _cmd_mcp(a) -> int:
+    home = resolve_home(a.home)
+    if not _enter(home):
+        return 2
+    from aon.mcp_server import run_stdio
+    run_stdio(CONFIG)
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="aon", description="AON, a self-hosted AI agent.")
+    p.add_argument("--version", action="version", version=f"aon {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    home_help = f"AON's home folder (default: $AON_HOME or {DEFAULT_HOME})"
+
+    i = sub.add_parser("init", help="create a home folder with a starter config")
+    i.add_argument("--home", help=home_help)
+    i.add_argument("--ollama", default="http://localhost:11434/v1", help="Ollama's /v1 URL")
+    i.add_argument("--model", default="qwen3:14b", help="chat model with tool support")
+    i.add_argument("--bind", default="127.0.0.1:8700", help="address:port for the web UI")
+    i.add_argument("--force", action="store_true", help="replace an existing config.toml")
+    i.set_defaults(fn=_cmd_init)
+
+    s = sub.add_parser("serve", help="run the web UI")
+    s.add_argument("--home", help=home_help)
+    s.add_argument("--host", help="override the host from config.toml")
+    s.add_argument("--port", type=int, help="override the port from config.toml")
+    s.set_defaults(fn=_cmd_serve)
+
+    m = sub.add_parser("mcp", help="run AON as an MCP server over stdio")
+    m.add_argument("--home", help=home_help)
+    m.set_defaults(fn=_cmd_mcp)
+
+    a = p.parse_args(argv)
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aon/composite_skills.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+
+class CompositeSkills:
+    def __init__(self, skill_store, mcp_manager=None):
+        self.store = skill_store
+        self.mcp = mcp_manager
+
+    def list(self):
+        out = list(self.store.list())
+        if self.mcp:
+            for p in self.mcp.prompts():
+                out.append((f"mcp:{p.server}:{p.name}", p.description))
+        return out
+
+    def items(self):
+        rows = [{"name": n, "desc": d, "source": "file"} for n, d in self.store.list()]
+        if self.mcp:
+            for p in self.mcp.prompts():
+                rows.append({"name": f"mcp:{p.server}:{p.name}", "desc": p.description, "source": "mcp"})
+        return rows
+
+    def read(self, name, path="SKILL.md"):
+        return self.store.read(name, path)
+
+    async def aread(self, name):
+        if name.startswith("mcp:"):
+            _, server, pname = name.split(":", 2)
+            return await self.mcp.get_prompt(server, pname)
+        return self.store.read(name)

aon/config.py

@@ -0,0 +1,64 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+import tomllib
+
+GUARDRAIL_PATHS: tuple[str, ...] = (
+    "src/aon/executor.py",
+    "src/aon/approval_gate.py",
+    "src/aon/telegram.py",
+)
+
+@dataclass
+class Config:
+    ollama_base_url: str
+    default_model: str
+    workdir: Path
+    always_ask: list[str]
+    max_steps: int
+    command_timeout: int
+    bind: str
+    telegram_bot_token: str | None = None
+    telegram_allowed_chat_ids: list[int] = field(default_factory=list)
+    # context budget: the model's window (Ollama num_ctx), room kept for thinking + the answer,
+    # and how much of a request the recent chat turns may take
+    context_window: int = 32768
+    reply_reserve: int = 6144
+    history_tokens: int = 8000
+    embed_model: str = "nomic-embed-text"
+    cross_chat_recall: bool = True       # bring relevant turns from the user's other chats
+    # a separate chat backend (vLLM) for one model; blank = all chat on Ollama
+    chat_base_url: str = ""
+    chat_model: str = ""
+    chat_temperature: float | None = None
+    chat_repetition_penalty: float | None = None
+    chat_top_p: float | None = None
+    chat_vision: bool = True             # the chat backend model can see images
+
+def load_config(path: Path) -> Config:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(path)
+    data = tomllib.loads(path.read_text())
+    return Config(
+        ollama_base_url=str(data["ollama_base_url"]),
+        default_model=str(data["default_model"]),
+        workdir=Path(str(data["workdir"])).expanduser(),
+        always_ask=list(data.get("always_ask", [])),
+        max_steps=int(data.get("max_steps", 40)),
+        command_timeout=int(data.get("command_timeout", 120)),
+        bind=str(data.get("bind", "127.0.0.1:8700")),
+        telegram_bot_token=(str(data["telegram_bot_token"]) or None)
+            if data.get("telegram_bot_token") else None,
+        telegram_allowed_chat_ids=[int(x) for x in data.get("telegram_allowed_chat_ids", [])],
+        context_window=int(data.get("context_window", 32768)),
+        reply_reserve=int(data.get("reply_reserve", 6144)),
+        history_tokens=int(data.get("history_tokens", 8000)),
+        embed_model=str(data.get("embed_model", "nomic-embed-text")),
+        cross_chat_recall=bool(data.get("cross_chat_recall", True)),
+        chat_base_url=str(data.get("chat_base_url", "")),
+        chat_model=str(data.get("chat_model", "")),
+        chat_temperature=(float(data["chat_temperature"]) if data.get("chat_temperature") is not None else None),
+        chat_repetition_penalty=(float(data["chat_repetition_penalty"]) if data.get("chat_repetition_penalty") is not None else None),
+        chat_top_p=(float(data["chat_top_p"]) if data.get("chat_top_p") is not None else None),
+        chat_vision=bool(data.get("chat_vision", True)),
+    )