comodor 0.1.0__py3-none-any.whl

comodor/config.py

@@ -0,0 +1,394 @@
+"""Layered configuration.
+
+Resolution order, later layers winning:
+
+    1. built-in defaults (this module)
+    2. ~/.comodor/config.toml             user preferences
+    3. ./.comodor/config.toml             project overrides, safe to commit
+    4. .env files + process environment  credentials
+    5. CLI flags                         one-off overrides
+
+Credentials deliberately live only in layer 4. Nothing that resolves an API key
+is ever written back to a TOML file, so a project config can be committed to a
+repository without leaking anything.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field, fields, is_dataclass
+from pathlib import Path
+from typing import Any
+
+from .paths import Paths, resolve as resolve_paths
+
+# --------------------------------------------------------------------------- #
+# provider catalogue
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class ProviderConfig:
+    """One reachable LLM backend.
+
+    ``kind`` selects the wire protocol: ``openai`` covers OpenRouter, Xiaomi
+    MiMo, DeepSeek, Groq, Together, Ollama and LM Studio — they differ only by
+    base URL and headers — while ``anthropic`` speaks the native Messages API.
+    """
+
+    name: str
+    kind: str = "openai"                 # "openai" | "anthropic" | "fake"
+    base_url: str = ""
+    api_key: str = ""
+    model: str = ""
+    label: str = ""                      # what the status bar shows
+    headers: dict[str, str] = field(default_factory=dict)
+    enabled: bool = True
+    timeout: float = 120.0
+    # True when the user actually said something about this provider — a key, an
+    # endpoint, or a config entry. Local runtimes are "ready" by default because
+    # they need no key, so without this signal Comodor would happily auto-select
+    # an Ollama that is not running and fail with a connection error.
+    explicit: bool = False
+
+    @property
+    def display(self) -> str:
+        return self.label or self.name.title()
+
+    @property
+    def local(self) -> bool:
+        return any(host in self.base_url for host in ("localhost", "127.0.0.1", "0.0.0.0"))
+
+    @property
+    def ready(self) -> bool:
+        """Local runtimes need no key; hosted ones do."""
+        return bool(self.base_url) and (bool(self.api_key) or self.local)
+
+    @property
+    def selectable(self) -> bool:
+        """Whether Comodor may choose this provider on the user's behalf."""
+        return self.enabled and self.ready and (not self.local or self.explicit)
+
+
+# name -> (label, kind, default base url, env var holding the key, default model)
+KNOWN_PROVIDERS: dict[str, tuple[str, str, str, str, str]] = {
+    "openrouter": ("Openrouter", "openai", "https://openrouter.ai/api/v1",
+                   "OPENROUTER_API_KEY", "anthropic/claude-sonnet-4.5"),
+    "anthropic": ("Anthropic", "anthropic", "https://api.anthropic.com/v1",
+                  "ANTHROPIC_API_KEY", "claude-sonnet-4-5"),
+    "openai": ("OpenAI", "openai", "https://api.openai.com/v1",
+               "OPENAI_API_KEY", "gpt-4o"),
+    "xiaomi": ("Xiaomi MiMo", "openai", "https://token-plan-sgp.xiaomimimo.com/v1",
+               "XIAOMI_API_KEY", "mimo-v2.5-pro"),
+    "deepseek": ("DeepSeek", "openai", "https://api.deepseek.com/v1",
+                 "DEEPSEEK_API_KEY", "deepseek-chat"),
+    "groq": ("Groq", "openai", "https://api.groq.com/openai/v1",
+             "GROQ_API_KEY", "llama-3.3-70b-versatile"),
+    "together": ("Together", "openai", "https://api.together.xyz/v1",
+                 "TOGETHER_API_KEY", "meta-llama/Llama-3.3-70B-Instruct-Turbo"),
+    "ollama": ("Ollama", "openai", "http://localhost:11434/v1",
+               "OLLAMA_API_KEY", "llama3.2"),
+    "lmstudio": ("LM Studio", "openai", "http://localhost:1234/v1",
+                 "LMSTUDIO_API_KEY", "local-model"),
+}
+
+# --------------------------------------------------------------------------- #
+# sections
+# --------------------------------------------------------------------------- #
+
+
+@dataclass
+class UIConfig:
+    theme: str = "ember"
+    ascii_borders: bool = False          # for terminals without box-drawing glyphs
+    mouse: bool = True
+    max_fps: int = 20                    # streaming deltas are coalesced to this
+    show_timestamps: bool = False
+    sidebar: bool = True
+    syntax_theme: str = "monokai"
+
+
+@dataclass
+class AgentConfig:
+    mode: str = "act"                    # act | plan | chat
+    loop: bool = True                    # autonomous multi-step iteration
+    max_steps: int = 24                  # hard stop for one task
+    max_seconds: float = 900.0
+    max_cost_usd: float = 2.0
+    context_limit: int = 1_000_000       # the "Context: 1M" gauge
+    compact_at: float = 0.75             # summarise history past this fraction
+    temperature: float = 0.3
+    max_output_tokens: int = 8192
+    system_prompt_extra: str = ""
+
+
+@dataclass
+class GatewayConfig:
+    """The GW indicator: route across providers instead of pinning one."""
+
+    enabled: bool = False                # matches the mockup's "GW: Disable"
+    policy: str = "quality"              # cost | speed | quality
+    chain: list[str] = field(default_factory=list)   # explicit failover order
+    failure_threshold: int = 3           # errors before a provider is tripped
+    cooldown_seconds: float = 60.0
+
+
+@dataclass
+class LearningConfig:
+    enabled: bool = True
+    top_k: int = 6                       # lessons recalled per turn
+    max_playbook_tokens: int = 800       # hard cap on injected memory
+    reflect: bool = True                 # distil lessons after each task
+    reflect_model: str = ""              # blank = the active model
+    min_confidence: float = 0.15         # below this a lesson is pruned
+    half_life_days: float = 45.0         # confidence decay
+    share_scope: str = "project"         # project | global — where new lessons land
+
+    # Reflex — the fast lane: deterministic, model-free, always on. It costs no
+    # tokens, so it stays enabled even when reflection is switched off.
+    corrections: bool = True             # learn from edits, undos and denials
+    rules: bool = True                   # keep a house-rules block in the prompt
+    announce: bool = True                # say so in the transcript when a rule lands
+    prefetch: bool = True                # warm recall while the user is typing
+
+
+@dataclass
+class SafetyConfig:
+    auto_approve_safe: bool = True       # read-only tools never prompt
+    auto_approve_writes: bool = False
+    auto_approve_shell: bool = False
+    checkpoints: bool = True             # snapshot files before mutating them
+    allow_commands: list[str] = field(default_factory=list)
+    deny_commands: list[str] = field(default_factory=lambda: list(DEFAULT_DENY))
+    workspace_only: bool = True          # refuse file writes outside the project
+    max_file_read_bytes: int = 512_000
+
+
+# Patterns that are never worth running from an agent, however it is prompted.
+DEFAULT_DENY: tuple[str, ...] = (
+    "rm -rf /",
+    "rm -rf ~",
+    "mkfs",
+    "dd if=",
+    "shutdown",
+    "reboot",
+    "format c:",
+    "del /f /s /q c:",
+    ":(){",                              # fork bomb
+    "> /dev/sda",
+    "chmod -R 777 /",
+)
+
+
+@dataclass
+class Config:
+    provider: str = "openrouter"
+    model: str = ""
+    ui: UIConfig = field(default_factory=UIConfig)
+    agent: AgentConfig = field(default_factory=AgentConfig)
+    gateway: GatewayConfig = field(default_factory=GatewayConfig)
+    learning: LearningConfig = field(default_factory=LearningConfig)
+    safety: SafetyConfig = field(default_factory=SafetyConfig)
+    providers: dict[str, ProviderConfig] = field(default_factory=dict)
+    paths: Paths = field(default_factory=resolve_paths)
+
+    # -- helpers ---------------------------------------------------------- #
+
+    def active(self) -> ProviderConfig | None:
+        return self.providers.get(self.provider)
+
+    def available(self) -> list[ProviderConfig]:
+        """Providers Comodor is willing to use without being told to."""
+        return [p for p in self.providers.values() if p.selectable]
+
+    def active_model(self) -> str:
+        if self.model:
+            return self.model
+        provider = self.active()
+        return provider.model if provider else ""
+
+    def to_public_dict(self) -> dict[str, Any]:
+        """Config with every secret removed — safe to display or export."""
+        data = _as_dict(self)
+        for entry in data.get("providers", {}).values():
+            if entry.get("api_key"):
+                entry["api_key"] = "***"
+            entry.pop("headers", None)
+        data.pop("paths", None)
+        return data
+
+
+# --------------------------------------------------------------------------- #
+# loading
+# --------------------------------------------------------------------------- #
+
+
+def _as_dict(obj: Any) -> Any:
+    if is_dataclass(obj) and not isinstance(obj, type):
+        return {f.name: _as_dict(getattr(obj, f.name)) for f in fields(obj)}
+    if isinstance(obj, dict):
+        return {k: _as_dict(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_as_dict(v) for v in obj]
+    if isinstance(obj, Path):
+        return str(obj)
+    return obj
+
+
+def _apply(section: Any, values: dict[str, Any]) -> None:
+    """Copy known keys onto a dataclass, ignoring unknown ones.
+
+    Unknown keys are tolerated rather than fatal: a config written by a newer
+    Comodor should not stop an older one from starting.
+    """
+    valid = {f.name for f in fields(section)}
+    for key, value in values.items():
+        if key not in valid:
+            continue
+        current = getattr(section, key)
+        if is_dataclass(current) and isinstance(value, dict):
+            _apply(current, value)
+        else:
+            setattr(section, key, value)
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as handle:
+            return tomllib.load(handle)
+    except FileNotFoundError:
+        return {}
+    except (tomllib.TOMLDecodeError, OSError):
+        # A broken config must never prevent startup; defaults carry the run.
+        return {}
+
+
+def _load_env_files(paths: Paths) -> None:
+    """Load .env files from every place a user might reasonably put one.
+
+    Earlier files win, matching the "closest to me" intuition: a key in the
+    project's .env should beat one in the home directory.
+    """
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        return
+    candidates = [
+        Path.cwd() / ".env",
+        Path.cwd() / "src" / ".env",
+        paths.project / ".env",
+        paths.project / "src" / ".env",
+        paths.user / ".env",
+    ]
+    seen: set[Path] = set()
+    for candidate in candidates:
+        resolved = candidate.expanduser()
+        if resolved in seen or not resolved.is_file():
+            continue
+        seen.add(resolved)
+        load_dotenv(resolved, override=False)
+
+
+def _build_providers(overrides: dict[str, Any]) -> dict[str, ProviderConfig]:
+    """Materialise the catalogue, folding in env vars and TOML overrides."""
+    providers: dict[str, ProviderConfig] = {}
+    for name, (label, kind, base_url, key_env, model) in KNOWN_PROVIDERS.items():
+        prefix = name.upper()
+        endpoint = (os.environ.get(f"{prefix}_ENDPOINT")
+                    or os.environ.get(f"{prefix}_BASE_URL"))
+        api_key = os.environ.get(key_env, "").strip()
+        providers[name] = ProviderConfig(
+            name=name,
+            kind=kind,
+            label=label,
+            base_url=endpoint or base_url,
+            api_key=api_key,
+            model=os.environ.get(f"{prefix}_MODEL") or model,
+            explicit=bool(endpoint or api_key),
+        )
+
+    # TOML may add entirely new providers (any OpenAI-compatible endpoint).
+    for name, values in (overrides or {}).items():
+        if not isinstance(values, dict):
+            continue
+        entry = providers.get(name) or ProviderConfig(name=name)
+        _apply(entry, values)
+        if not entry.api_key and values.get("api_key_env"):
+            entry.api_key = os.environ.get(str(values["api_key_env"]), "").strip()
+        entry.explicit = True            # naming it in a config file is intent
+        providers[name] = entry
+    return providers
+
+
+def load(cwd: Path | str | None = None, overrides: dict[str, Any] | None = None) -> Config:
+    """Resolve the full configuration for one run."""
+    paths = resolve_paths(cwd).ensure()
+    _load_env_files(paths)
+
+    merged: dict[str, Any] = {}
+    for source in (_load_toml(paths.config_file), _load_toml(paths.project_config_file)):
+        for key, value in source.items():
+            if isinstance(value, dict) and isinstance(merged.get(key), dict):
+                merged[key].update(value)
+            else:
+                merged[key] = value
+
+    config = Config(paths=paths)
+    config.providers = _build_providers(merged.get("providers", {}))
+    _apply(config, {k: v for k, v in merged.items() if k != "providers"})
+
+    if overrides:
+        _apply(config, overrides)
+
+    # Pick a sensible default provider: honour the configured choice when it is
+    # usable, otherwise fall back to whichever provider the user has actually
+    # set up. Local runtimes only qualify if they were named explicitly —
+    # otherwise a machine with no keys would silently select an Ollama that is
+    # not running and fail with a connection error instead of a useful one.
+    active = config.providers.get(config.provider)
+    if active is None or not active.ready:
+        for candidate in ("openrouter", "anthropic", "openai", "xiaomi",
+                          "deepseek", "groq", "together", "ollama", "lmstudio"):
+            entry = config.providers.get(candidate)
+            if entry and entry.selectable:
+                config.provider = candidate
+                config.model = ""        # the old model belonged to the old provider
+                break
+    if not config.model:
+        active = config.active()
+        config.model = active.model if active else ""
+    return config
+
+
+def save_user_config(config: Config) -> Path:
+    """Persist the non-secret parts of the config to the user TOML file."""
+    data = config.to_public_dict()
+    data.pop("providers", None)          # provider keys stay in the environment
+    target = config.paths.config_file
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(_dump_toml(data), encoding="utf-8")
+    return target
+
+
+def _dump_toml(data: dict[str, Any], prefix: str = "") -> str:
+    """Minimal TOML writer — enough for our flat, typed config tree."""
+    scalars: list[str] = []
+    tables: list[str] = []
+    for key, value in data.items():
+        if isinstance(value, dict):
+            tables.append(f"\n[{prefix}{key}]\n" + _dump_toml(value, f"{prefix}{key}."))
+        else:
+            scalars.append(f"{key} = {_toml_value(value)}")
+    return "\n".join(scalars) + ("\n" if scalars else "") + "".join(tables)
+
+
+def _toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_toml_value(v) for v in value) + "]"
+    escaped = str(value).replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    return f'"{escaped}"'

comodor/events.py

@@ -0,0 +1,211 @@
+"""The one channel between the agent worker and the UI thread.
+
+The agent runs in a background thread; Rich renders from the main thread. They
+share no mutable state — the worker only *emits* events and the UI only *reads*
+them. That rule is what keeps the interface responsive while a tool is running
+and makes the whole agent reusable headlessly: swap the subscriber and the same
+loop drives a JSON stream instead of a terminal.
+
+One flow needs to go the other way — asking the user to approve a tool call —
+so :class:`Request` carries its own reply slot. The worker blocks on it while
+the UI keeps painting.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Iterator
+
+
+class Kind(str, Enum):
+    """Every event the agent can emit."""
+
+    # conversation
+    USER_MESSAGE = "user_message"
+    ASSISTANT_START = "assistant_start"
+    ASSISTANT_DELTA = "assistant_delta"          # streamed token(s)
+    ASSISTANT_END = "assistant_end"
+    REASONING_DELTA = "reasoning_delta"          # extended-thinking stream
+
+    # tools
+    TOOL_START = "tool_start"
+    TOOL_OUTPUT = "tool_output"                  # incremental output (shell)
+    TOOL_END = "tool_end"
+
+    # lifecycle
+    TURN_START = "turn_start"
+    TURN_END = "turn_end"
+    STEP = "step"                                # one loop iteration completed
+    CANCELLED = "cancelled"
+
+    # side channels
+    STATUS = "status"                            # provider/model/connection
+    USAGE = "usage"                              # tokens + cost + context fill
+    MEMORY = "memory"                            # lessons recalled or learned
+    TODO = "todo"                                # task list changed
+    NOTICE = "notice"                            # transient toast
+    ERROR = "error"
+    REQUEST = "request"                          # needs an answer from the user
+
+
+@dataclass(slots=True)
+class Event:
+    kind: Kind
+    payload: dict[str, Any] = field(default_factory=dict)
+    at: float = field(default_factory=time.time)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.payload.get(key, default)
+
+    @property
+    def text(self) -> str:
+        return str(self.payload.get("text", ""))
+
+
+@dataclass
+class Request:
+    """A question the worker needs answered before it can continue.
+
+    Used for permission prompts. The worker calls :meth:`wait`; the UI renders
+    the dialog and calls :meth:`answer`. A timeout means "denied", so a
+    forgotten prompt can never wedge the agent forever.
+    """
+
+    id: str
+    prompt: str
+    options: list[str]
+    detail: str = ""
+    kind: str = "permission"
+    meta: dict[str, Any] = field(default_factory=dict)
+    _done: threading.Event = field(default_factory=threading.Event, repr=False)
+    _answer: str | None = field(default=None, repr=False)
+
+    def answer(self, choice: str) -> None:
+        self._answer = choice
+        self._done.set()
+
+    def wait(self, timeout: float | None = None) -> str:
+        if self._done.wait(timeout):
+            return self._answer or (self.options[-1] if self.options else "no")
+        return self.options[-1] if self.options else "no"
+
+    @property
+    def answered(self) -> bool:
+        return self._done.is_set()
+
+
+Subscriber = Callable[[Event], None]
+
+
+class EventBus:
+    """Fan-out queue: every subscriber sees every event, in order.
+
+    Subscribers are called on the emitting thread, so they must be cheap — the
+    UI subscriber just appends to its own queue and returns.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: list[Subscriber] = []
+        self._lock = threading.Lock()
+        self._closed = False
+
+    def subscribe(self, subscriber: Subscriber) -> Callable[[], None]:
+        with self._lock:
+            self._subscribers.append(subscriber)
+
+        def unsubscribe() -> None:
+            with self._lock:
+                if subscriber in self._subscribers:
+                    self._subscribers.remove(subscriber)
+
+        return unsubscribe
+
+    def emit(self, kind: Kind, **payload: Any) -> Event:
+        event = Event(kind=kind, payload=payload)
+        self.publish(event)
+        return event
+
+    def publish(self, event: Event) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            targets = list(self._subscribers)
+        for subscriber in targets:
+            try:
+                subscriber(event)
+            except Exception:
+                # A broken subscriber must never take down the agent mid-task.
+                pass
+
+    def ask(self, request: Request) -> Request:
+        """Emit a question and hand the caller the object to wait on."""
+        self.publish(Event(kind=Kind.REQUEST, payload={"request": request}))
+        return request
+
+    def close(self) -> None:
+        with self._lock:
+            self._closed = True
+            self._subscribers.clear()
+
+
+class EventQueue:
+    """A subscriber that buffers events for a consumer to drain at its own pace.
+
+    The UI drains this once per frame: rendering never blocks the agent, and a
+    burst of stream deltas collapses into a single repaint.
+    """
+
+    def __init__(self, bus: EventBus, maxsize: int = 0) -> None:
+        self._queue: queue.Queue[Event] = queue.Queue(maxsize)
+        self._unsubscribe = bus.subscribe(self._queue.put)
+
+    def drain(self, limit: int = 512) -> list[Event]:
+        events: list[Event] = []
+        for _ in range(limit):
+            try:
+                events.append(self._queue.get_nowait())
+            except queue.Empty:
+                break
+        return events
+
+    def wait(self, timeout: float) -> Event | None:
+        try:
+            return self._queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def __iter__(self) -> Iterator[Event]:
+        while True:
+            yield self._queue.get()
+
+    def close(self) -> None:
+        self._unsubscribe()
+
+
+class Cancellation:
+    """Cooperative cancellation, checked between agent steps and stream chunks."""
+
+    def __init__(self) -> None:
+        self._flag = threading.Event()
+
+    def cancel(self) -> None:
+        self._flag.set()
+
+    def reset(self) -> None:
+        self._flag.clear()
+
+    @property
+    def cancelled(self) -> bool:
+        return self._flag.is_set()
+
+    def raise_if_cancelled(self) -> None:
+        if self._flag.is_set():
+            raise Cancelled()
+
+
+class Cancelled(Exception):
+    """Raised inside the worker when the user pressed Esc."""

comodor/learning/__init__.py

@@ -0,0 +1,8 @@
+"""The persistent brain: recall, reinforcement, reflection, consolidation."""
+
+from .bm25 import BM25Index, similarity, tokenize
+from .memory import LearningEngine
+from .store import BrainStore, Episode, Lesson, Skill
+
+__all__ = ["LearningEngine", "BrainStore", "Lesson", "Skill", "Episode",
+           "BM25Index", "tokenize", "similarity"]