docent-cli 1.0.0__py3-none-any.whl

docent/core/registry.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import TypeVar
+
+from pydantic import BaseModel
+
+from docent.core.tool import Tool, collect_actions
+
+_REGISTRY: dict[str, type[Tool]] = {}
+_RESERVED_NAMES = frozenset({"list", "info", "config", "version"})
+
+T = TypeVar("T", bound=Tool)
+
+
+def register_tool(cls: type[T]) -> type[T]:
+    """Decorator: validate a Tool subclass and add it to the registry.
+
+    Registers the *class*, not an instance. Instances are created per
+    invocation by the caller (CLI command, UI request handler, etc.) so
+    tool runs never share mutable state.
+    """
+    if not isinstance(cls, type) or not issubclass(cls, Tool):
+        raise TypeError(
+            f"@register_tool must decorate a Tool subclass; got {cls!r}"
+        )
+
+    for attr in ("name", "description"):
+        if not hasattr(cls, attr):
+            raise TypeError(
+                f"Tool {cls.__name__} is missing required class attribute '{attr}'"
+            )
+
+    if not isinstance(cls.name, str) or not cls.name:
+        raise TypeError(
+            f"Tool {cls.__name__}.name must be a non-empty string"
+        )
+
+    if cls.name in _RESERVED_NAMES:
+        raise ValueError(
+            f"Tool name '{cls.name}' is reserved for a built-in CLI command; choose another"
+        )
+
+    actions = collect_actions(cls)
+    has_run = "run" in cls.__dict__
+    has_input_schema = cls.input_schema is not None
+
+    if actions and (has_run or has_input_schema):
+        raise TypeError(
+            f"Tool {cls.__name__} declares both @action methods and run()/input_schema. "
+            f"A tool must be single-action OR multi-action, not both."
+        )
+
+    if not actions:
+        if not has_run:
+            raise TypeError(
+                f"Tool {cls.__name__} must define run() or at least one @action method"
+            )
+        if not has_input_schema:
+            raise TypeError(
+                f"Tool {cls.__name__}.input_schema must be set for single-action tools"
+            )
+        if not (isinstance(cls.input_schema, type) and issubclass(cls.input_schema, BaseModel)):
+            raise TypeError(
+                f"Tool {cls.__name__}.input_schema must be a Pydantic BaseModel subclass"
+            )
+    else:
+        for cli_name, (method_name, meta) in actions.items():
+            if not (
+                isinstance(meta.input_schema, type)
+                and issubclass(meta.input_schema, BaseModel)
+            ):
+                raise TypeError(
+                    f"Tool {cls.__name__}.{method_name}: @action input_schema must be a "
+                    f"Pydantic BaseModel subclass"
+                )
+
+    if cls.name in _REGISTRY:
+        existing = _REGISTRY[cls.name]
+        raise ValueError(
+            f"Tool name '{cls.name}' is already registered by "
+            f"{existing.__module__}.{existing.__name__}; cannot re-register "
+            f"from {cls.__module__}.{cls.__name__}"
+        )
+
+    _REGISTRY[cls.name] = cls
+    return cls
+
+
+def get_tool(name: str) -> type[Tool]:
+    if name not in _REGISTRY:
+        raise KeyError(f"No tool registered with name '{name}'")
+    return _REGISTRY[name]
+
+
+def all_tools() -> dict[str, type[Tool]]:
+    return dict(_REGISTRY)

docent/core/tool.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from abc import ABC
+from dataclasses import dataclass
+from typing import Any, Callable, ClassVar, TypeVar
+
+from pydantic import BaseModel
+
+from docent.core.context import Context
+
+
+@dataclass(frozen=True)
+class Action:
+    """Metadata attached to a method by `@action`.
+
+    The registry introspects each Tool class for methods carrying an `Action`
+    via `_docent_action`. CLI name defaults to the method name with
+    underscores → dashes (override via `name=`).
+    """
+
+    description: str
+    input_schema: type[BaseModel]
+    name: str | None = None
+
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def action(
+    *,
+    description: str,
+    input_schema: type[BaseModel],
+    name: str | None = None,
+) -> Callable[[F], F]:
+    """Decorator: mark a method on a Tool as an invocable action."""
+
+    def decorator(fn: F) -> F:
+        fn._docent_action = Action(  # type: ignore[attr-defined]
+            description=description, input_schema=input_schema, name=name
+        )
+        return fn
+
+    return decorator
+
+
+class Tool(ABC):
+    """Base class for every Docent tool.
+
+    Two paths:
+    - **Single-action**: set `input_schema` and override `run()`.
+    - **Multi-action**: decorate one or more methods with `@action(...)`.
+
+    A tool must be one or the other - never both. Enforced at registration.
+    Metadata lives as class attributes so the registry (and later the UI)
+    can read it without constructing an instance.
+    """
+
+    name: ClassVar[str]
+    description: ClassVar[str]
+    category: ClassVar[str | None] = None
+
+    input_schema: ClassVar[type[BaseModel] | None] = None
+
+    def run(self, inputs: BaseModel, context: Context) -> Any:
+        """Single-action entry point. Multi-action tools don't override this."""
+        raise NotImplementedError(
+            f"{type(self).__name__}.run() not implemented - "
+            f"is this a multi-action tool? Invoke one of its @action methods instead."
+        )
+
+
+def collect_actions(cls: type[Tool]) -> dict[str, tuple[str, Action]]:
+    """Return `{cli_action_name: (method_name, Action)}` for all `@action` methods.
+
+    Raises `ValueError` on CLI-name collisions between actions.
+    """
+    found: dict[str, tuple[str, Action]] = {}
+    for attr_name in dir(cls):
+        attr = getattr(cls, attr_name, None)
+        if callable(attr) and hasattr(attr, "_docent_action"):
+            meta: Action = attr._docent_action  # type: ignore[attr-defined]
+            cli_name = meta.name or attr_name.replace("_", "-")
+            if cli_name in found:
+                prev_method = found[cli_name][0]
+                raise ValueError(
+                    f"Tool {cls.__name__} has two actions with the same CLI name "
+                    f"'{cli_name}': {prev_method} and {attr_name}"
+                )
+            found[cli_name] = (attr_name, meta)
+    return found

docent/execution/__init__.py

@@ -0,0 +1,3 @@
+from docent.execution.executor import Executor, ProcessExecutionError, ProcessResult
+
+__all__ = ["Executor", "ProcessExecutionError", "ProcessResult"]

docent/execution/executor.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ProcessResult:
+    args: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    duration: float
+
+
+class ProcessExecutionError(RuntimeError):
+    """Raised by `Executor.run` when `check=True` and the process exits non-zero."""
+
+    def __init__(self, result: ProcessResult) -> None:
+        self.result = result
+        super().__init__(
+            f"Command {result.args!r} exited with {result.returncode} "
+            f"after {result.duration:.2f}s"
+        )
+
+
+class Executor:
+    """Run external commands and return structured results.
+
+    Commands are always given as `list[str]` - never a shell string - so there
+    is no shell-injection surface. For tools that truly need shell features,
+    pass `["bash", "-c", "..."]` (or `["cmd", "/c", "..."]`) explicitly.
+    """
+
+    def run(
+        self,
+        args: list[str],
+        *,
+        timeout: float | None = None,
+        cwd: Path | str | None = None,
+        env: dict[str, str] | None = None,
+        check: bool = True,
+    ) -> ProcessResult:
+        start = time.perf_counter()
+        completed = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=cwd,
+            env=env,
+            check=False,
+        )
+        duration = time.perf_counter() - start
+
+        result = ProcessResult(
+            args=list(args),
+            returncode=completed.returncode,
+            stdout=completed.stdout,
+            stderr=completed.stderr,
+            duration=duration,
+        )
+
+        if check and completed.returncode != 0:
+            raise ProcessExecutionError(result)
+
+        return result

docent/learning/__init__.py

@@ -0,0 +1,3 @@
+from docent.learning.run_log import RunLog
+
+__all__ = ["RunLog"]

docent/learning/run_log.py

@@ -0,0 +1,69 @@
+"""Per-namespace run-log helpers.
+
+A `RunLog(namespace)` is a JSONL file at `~/.docent/data/<namespace>/run-log.jsonl`
+capped at `max_lines` (default 50). Append is cheap (single line write); tail is
+cheap (read + split); rollover rewrites atomically when the cap is hit.
+
+Entries are free-form JSON dicts. A `timestamp` field is auto-added on append
+if the caller didn't supply one.
+"""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from docent.utils.paths import data_dir
+
+
+class RunLog:
+    def __init__(self, namespace: str, *, max_lines: int = 50) -> None:
+        if not namespace or "/" in namespace or "\\" in namespace:
+            raise ValueError(f"Invalid namespace: {namespace!r}")
+        if max_lines < 1:
+            raise ValueError(f"max_lines must be >= 1, got {max_lines}")
+        self.namespace = namespace
+        self.max_lines = max_lines
+
+    @property
+    def path(self) -> Path:
+        return data_dir() / self.namespace / "run-log.jsonl"
+
+    def append(self, entry: dict[str, Any]) -> None:
+        record = dict(entry)
+        record.setdefault("timestamp", datetime.now().isoformat())
+        line = json.dumps(record, ensure_ascii=False)
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        existing = self._read_lines()
+
+        if len(existing) >= self.max_lines:
+            kept = existing[-(self.max_lines - 1):] if self.max_lines > 1 else []
+            self._atomic_rewrite(kept + [line])
+        else:
+            with self.path.open("a", encoding="utf-8") as f:
+                f.write(line + "\n")
+
+    def tail(self, n: int) -> list[dict[str, Any]]:
+        if n < 0:
+            raise ValueError(f"n must be >= 0, got {n}")
+        if n == 0:
+            return []
+        lines = self._read_lines()
+        return [json.loads(line) for line in lines[-n:]]
+
+    def all(self) -> list[dict[str, Any]]:
+        return [json.loads(line) for line in self._read_lines()]
+
+    def _read_lines(self) -> list[str]:
+        if not self.path.exists():
+            return []
+        text = self.path.read_text(encoding="utf-8")
+        return [line for line in text.splitlines() if line.strip()]
+
+    def _atomic_rewrite(self, lines: list[str]) -> None:
+        tmp = self.path.with_suffix(self.path.suffix + ".tmp")
+        tmp.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+        os.replace(tmp, self.path)

docent/llm/__init__.py

@@ -0,0 +1,3 @@
+from docent.llm.client import LLMClient, LLMResponse
+
+__all__ = ["LLMClient", "LLMResponse"]

docent/llm/client.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from docent.config import Settings
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    text: str
+    model: str
+
+
+class LLMClient:
+    """Thin wrapper around litellm. The single entry point for model calls.
+
+    litellm is imported lazily inside `complete()` so meta-commands
+    (`--version`, `list`, `info`) never pay the ~1s import cost.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        # Propagate config-provided API keys into env if the env var is unset.
+        # Env vars set by the user always win.
+        if settings.anthropic_api_key and not os.environ.get("ANTHROPIC_API_KEY"):
+            os.environ["ANTHROPIC_API_KEY"] = settings.anthropic_api_key
+        if settings.openai_api_key and not os.environ.get("OPENAI_API_KEY"):
+            os.environ["OPENAI_API_KEY"] = settings.openai_api_key
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        system: str | None = None,
+        model: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+    ) -> LLMResponse:
+        import litellm
+
+        messages: list[dict[str, str]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        kwargs: dict[str, object] = {}
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        response = litellm.completion(
+            model=model or self.settings.default_model,
+            messages=messages,
+            temperature=temperature,
+            num_retries=2,
+            **kwargs,
+        )
+
+        text = response.choices[0].message.content or ""
+        return LLMResponse(text=text, model=response.model)

docent/mcp_server.py

@@ -0,0 +1,187 @@
+"""Step 13 — Full MCP adapter.
+
+Exposes every registered Docent action as an MCP tool callable from Claude Code
+(or any other MCP-compatible client) over stdio.
+
+Tool naming convention: `{tool_name}__{action_name}` where the action's CLI name
+has hyphens replaced by underscores.
+
+  Example: reading tool's `sync-from-mendeley` → `reading__sync_from_mendeley`
+
+The double-underscore separator is unambiguous: tool names are single-word
+identifiers (`reading`, `paper`) and action names never contain `__`.
+
+Usage:
+    docent serve                     # recommended — loads plugins first
+
+Claude Code .mcp.json:
+    {
+      "mcpServers": {
+        "docent": {
+          "command": "uv",
+          "args": ["--directory", "<project-root>", "run", "docent", "serve"]
+        }
+      }
+    }
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from typing import Any
+
+from mcp import types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from pydantic import BaseModel
+
+from docent.config import load_settings
+from docent.core import (
+    Context,
+    ProgressEvent,
+    all_tools,
+    collect_actions,
+    load_plugins,
+)
+from docent.execution import Executor
+from docent.llm import LLMClient
+from docent.tools import discover_tools
+
+
+# ---------------------------------------------------------------------------
+# Naming helpers
+# ---------------------------------------------------------------------------
+
+def mcp_tool_name(tool_name: str, action_cli_name: str) -> str:
+    """Build the MCP tool name from a (tool, action) pair."""
+    return f"{tool_name}__{action_cli_name.replace('-', '_')}"
+
+
+def parse_mcp_tool_name(mcp_name: str) -> tuple[str, str] | None:
+    """Return (tool_name, action_cli_name) or None if the name is not a Docent tool."""
+    if "__" not in mcp_name:
+        return None
+    tool_name, action_part = mcp_name.split("__", 1)
+    action_cli_name = action_part.replace("_", "-")
+    return tool_name, action_cli_name
+
+
+# ---------------------------------------------------------------------------
+# Registry introspection
+# ---------------------------------------------------------------------------
+
+def build_mcp_tools() -> list[types.Tool]:
+    """Return one MCP Tool descriptor per (tool, action) pair in the registry."""
+    result = []
+    for tool_name, tool_cls in sorted(all_tools().items()):
+        for action_cli_name, (_method, meta) in sorted(collect_actions(tool_cls).items()):
+            result.append(
+                types.Tool(
+                    name=mcp_tool_name(tool_name, action_cli_name),
+                    description=f"[{tool_name}] {meta.description}",
+                    inputSchema=meta.input_schema.model_json_schema(),
+                )
+            )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Action invocation
+# ---------------------------------------------------------------------------
+
+def _make_context() -> Context:
+    settings = load_settings()
+    return Context(settings=settings, llm=LLMClient(settings), executor=Executor())
+
+
+def _serialize(result: Any) -> str:
+    if isinstance(result, BaseModel):
+        return result.model_dump_json(indent=2)
+    try:
+        return json.dumps(result, indent=2, default=str)
+    except Exception:
+        return str(result)
+
+
+def invoke_action(
+    tool_name: str,
+    action_cli_name: str,
+    arguments: dict[str, Any],
+) -> str:
+    """Run one Docent action and return its result as a JSON string.
+
+    Generator actions (streaming) collect ProgressEvent messages as a
+    prefix and the final return value as the last line.
+    """
+    tools = all_tools()
+    if tool_name not in tools:
+        raise ValueError(f"No tool named '{tool_name}'")
+
+    tool_cls = tools[tool_name]
+    actions = collect_actions(tool_cls)
+    if action_cli_name not in actions:
+        raise ValueError(f"Tool '{tool_name}' has no action '{action_cli_name}'")
+
+    method_name, meta = actions[action_cli_name]
+    inputs = meta.input_schema(**arguments)
+    ctx = _make_context()
+    method = getattr(tool_cls(), method_name)
+    raw = method(inputs, ctx)
+
+    if inspect.isgenerator(raw):
+        lines: list[str] = []
+        try:
+            while True:
+                evt = next(raw)
+                if isinstance(evt, ProgressEvent) and evt.message:
+                    lines.append(f"[{evt.phase}] {evt.message}")
+        except StopIteration as stop:
+            lines.append(_serialize(stop.value))
+        return "\n".join(lines)
+
+    return _serialize(raw)
+
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+def run_server() -> None:
+    """Load plugins, build the MCP tool list, and serve over stdio.
+
+    Called by `docent serve`. Blocks until the client disconnects.
+    """
+    import sys
+    discover_tools()
+    load_plugins()
+    tools = build_mcp_tools()
+    print(f"[docent] MCP server ready — {len(tools)} tools registered. Waiting for client…", file=sys.stderr, flush=True)
+
+    server = Server("docent")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return build_mcp_tools()
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+        parsed = parse_mcp_tool_name(name)
+        if parsed is None:
+            return [types.TextContent(type="text", text=f"Unknown tool format: {name!r}")]
+        tool_name, action_cli_name = parsed
+        try:
+            text = invoke_action(tool_name, action_cli_name, arguments or {})
+            return [types.TextContent(type="text", text=text)]
+        except Exception as exc:
+            return [types.TextContent(type="text", text=f"Error: {exc}")]
+
+    async def _serve() -> None:
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+    asyncio.run(_serve())

docent/tools/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import importlib
+import pkgutil
+
+
+def discover_tools() -> None:
+    """Import every module in `docent.tools` so `@register_tool` fires.
+
+    Each `.py` in this package is treated as a tool module. Names beginning
+    with `_` are skipped so tests and scratch modules can coexist without
+    being auto-loaded.
+    """
+    for _, name, _ in pkgutil.iter_modules(__path__):
+        if name.startswith("_"):
+            continue
+        importlib.import_module(f"{__name__}.{name}")

docent/ui/__init__.py

@@ -0,0 +1,3 @@
+from docent.ui.console import configure_console, get_console
+
+__all__ = ["configure_console", "get_console"]

docent/ui/console.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from rich.console import Console
+
+from docent.ui.theme import docent_theme
+
+_console: Console | None = None
+
+
+def get_console() -> Console:
+    global _console
+    if _console is None:
+        _console = Console(theme=docent_theme)
+    return _console
+
+
+def configure_console(*, no_color: bool = False, quiet: bool = False) -> Console:
+    """Replace the singleton with one matching the given flags.
+
+    Called once from the CLI root callback, after parsing global flags.
+    """
+    global _console
+    _console = Console(
+        theme=docent_theme,
+        no_color=no_color,
+        quiet=quiet,
+    )
+    return _console

docent/ui/theme.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from rich.theme import Theme
+
+docent_theme = Theme(
+    {
+        "success": "bold green",
+        "error": "bold red",
+        "warning": "yellow",
+        "info": "cyan",
+        "muted": "dim white",
+        "accent": "bold magenta",
+        "header": "bold",
+        "prompt": "bold cyan",
+    }
+)