docent-cli 1.0.0__py3-none-any.whl

docent/cli.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable
+
+import typer
+from pydantic import BaseModel
+from rich import box
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+from rich.table import Table
+
+from docent import __version__
+from docent.config import load_settings
+from docent.core import (
+    Context,
+    ProgressEvent,
+    Tool,
+    all_tools,
+    collect_actions,
+    load_plugins,
+    run_startup_hooks,
+)
+from docent.execution import Executor
+from docent.llm import LLMClient
+from docent.tools import discover_tools
+from docent.ui import configure_console, get_console
+
+app = typer.Typer(
+    name="docent",
+    help="Docent — a personal control center for grad school workflows.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"docent {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Show the Docent version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Verbose output.",
+    ),
+    no_color: bool = typer.Option(
+        False,
+        "--no-color",
+        help="Disable colored output.",
+    ),
+) -> None:
+    """Docent — grad-school workflow dispatcher."""
+    settings = load_settings()
+    settings.verbose = verbose or settings.verbose
+    settings.no_color = no_color or settings.no_color
+
+    configure_console(no_color=settings.no_color)
+
+    ctx.obj = Context(settings=settings, llm=LLMClient(settings), executor=Executor())
+    run_startup_hooks(ctx.obj)
+
+
+@app.command("list", help="List all registered tools.")
+def list_command(ctx: typer.Context) -> None:
+    console = get_console()
+    tools = all_tools()
+    if not tools:
+        console.print("[dim]No tools registered yet.[/]")
+        return
+
+    by_category: dict[str, list[type[Tool]]] = {}
+    for tool_cls in tools.values():
+        by_category.setdefault(tool_cls.category or "Uncategorized", []).append(tool_cls)
+
+    for category, group in sorted(by_category.items()):
+        table = Table(title=category, box=box.ROUNDED, show_header=True, header_style="bold")
+        table.add_column("Name", style="cyan", no_wrap=True)
+        table.add_column("Description")
+        for tc in sorted(group, key=lambda c: c.name):
+            actions = collect_actions(tc)
+            name_display = tc.name if not actions else f"{tc.name}  ({len(actions)} actions)"
+            table.add_row(name_display, tc.description)
+        console.print(table)
+
+
+@app.command("info", help="Show details about a registered tool.")
+def info_command(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Name of the tool."),
+) -> None:
+    console = get_console()
+    tools = all_tools()
+    if name not in tools:
+        console.print(f"[red]No tool named '{name}'.[/]")
+        raise typer.Exit(2)
+
+    tool_cls = tools[name]
+    lines = [
+        f"[bold]Name:[/] {tool_cls.name}",
+        f"[bold]Category:[/] {tool_cls.category or 'Uncategorized'}",
+        f"[bold]Description:[/] {tool_cls.description}",
+    ]
+
+    actions = collect_actions(tool_cls)
+    if actions:
+        lines.append("")
+        lines.append(f"[bold]Actions ({len(actions)}):[/]")
+        for cli_name, (_method_name, meta) in sorted(actions.items()):
+            lines.append(f"  [cyan]{cli_name}[/] - {meta.description}")
+            for fname, finfo in meta.input_schema.model_fields.items():
+                lines.append(f"      {_format_field(fname, finfo)}")
+    else:
+        assert tool_cls.input_schema is not None
+        lines.append("")
+        lines.append("[bold]Inputs:[/]")
+        for fname, finfo in tool_cls.input_schema.model_fields.items():
+            lines.append(f"  {_format_field(fname, finfo)}")
+
+    console.print(Panel("\n".join(lines), title=tool_cls.name, border_style="cyan"))
+
+
+def _format_field(fname: str, finfo: Any) -> str:
+    status = "(required)" if finfo.is_required() else f"(default={finfo.default!r})"
+    annot = getattr(finfo.annotation, "__name__", str(finfo.annotation))
+    desc = f" - {finfo.description}" if finfo.description else ""
+    return f"--{fname.replace('_', '-')}: {annot} {status}{desc}"
+
+
+def _drive_progress(gen: Any) -> Any:
+    """Drive a generator-based action, rendering events with Rich Progress.
+
+    Phase changes swap to a fresh task. Events with (current, total) advance
+    a bar; events without it (or with level=warn/error) print a console line.
+    The action's `return` value is captured from `StopIteration.value`.
+    """
+    console = get_console()
+    columns = (
+        SpinnerColumn(),
+        TextColumn("[bold cyan]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn("[dim]{task.fields[item]}"),
+        TimeElapsedColumn(),
+    )
+    result: Any = None
+    with Progress(*columns, console=console, transient=False) as progress:
+        task_id: int | None = None
+        current_phase: str | None = None
+        try:
+            while True:
+                evt = next(gen)
+                if not isinstance(evt, ProgressEvent):
+                    progress.console.print(f"[yellow]warn[/] non-event yielded: {evt!r}")
+                    continue
+                if evt.level in ("warn", "error"):
+                    tag = "[yellow]warn[/]" if evt.level == "warn" else "[red]error[/]"
+                    text = evt.message or (f"{evt.phase}: {evt.item}" if evt.item else evt.phase)
+                    progress.console.print(f"{tag} {text}")
+                    continue
+                if evt.total is not None:
+                    if task_id is None or evt.phase != current_phase:
+                        if task_id is not None:
+                            progress.remove_task(task_id)
+                        task_id = progress.add_task(
+                            evt.phase, total=evt.total, item=evt.item or ""
+                        )
+                        current_phase = evt.phase
+                    progress.update(
+                        task_id, completed=evt.current or 0, item=evt.item or ""
+                    )
+                elif evt.message:
+                    progress.console.print(f"[dim]{evt.phase}[/] {evt.message}")
+        except StopIteration as stop:
+            result = stop.value
+    return result
+
+
+def _build_callback(
+    schema: type[BaseModel],
+    invoke: Callable[[BaseModel, Context], Any],
+    name: str,
+    doc: str,
+) -> Any:
+    """Build a Typer callback with a synthesized signature from a Pydantic schema.
+
+    `invoke(inputs, context)` is called with validated inputs and the Context
+    from `ctx.obj`. Its return value (if not None) is printed via the CLI's
+    console singleton.
+    """
+
+    def callback(**kwargs: Any) -> None:
+        ctx: typer.Context = kwargs.pop("ctx")
+        inputs = schema(**kwargs)
+        context: Context = ctx.obj
+        maybe = invoke(inputs, context)
+        result = _drive_progress(maybe) if inspect.isgenerator(maybe) else maybe
+        if result is not None:
+            get_console().print(result)
+
+    params = [
+        inspect.Parameter("ctx", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=typer.Context),
+    ]
+    annotations: dict[str, Any] = {"ctx": typer.Context}
+
+    for fname, finfo in schema.model_fields.items():
+        cli_flag = "--" + fname.replace("_", "-")
+        help_text = finfo.description or ""
+        option_default = ... if finfo.is_required() else finfo.default
+        option = typer.Option(option_default, cli_flag, help=help_text)
+        params.append(
+            inspect.Parameter(
+                fname,
+                inspect.Parameter.KEYWORD_ONLY,
+                default=option,
+                annotation=finfo.annotation,
+            )
+        )
+        annotations[fname] = finfo.annotation
+
+    callback.__signature__ = inspect.Signature(params)  # type: ignore[attr-defined]
+    callback.__annotations__ = annotations
+    callback.__name__ = name
+    callback.__doc__ = doc
+    return callback
+
+
+def _register_tool_in_app(tool_cls: type[Tool]) -> None:
+    """Attach a single- or multi-action tool to the top-level Typer app."""
+    actions = collect_actions(tool_cls)
+
+    if not actions:
+        assert tool_cls.input_schema is not None
+        callback = _build_callback(
+            schema=tool_cls.input_schema,
+            invoke=lambda inp, ctx: tool_cls().run(inp, ctx),
+            name=tool_cls.name.replace("-", "_"),
+            doc=tool_cls.description,
+        )
+        app.command(name=tool_cls.name, help=tool_cls.description)(callback)
+        return
+
+    subapp = typer.Typer(
+        name=tool_cls.name,
+        help=tool_cls.description,
+        no_args_is_help=True,
+        add_completion=False,
+    )
+    for cli_name, (method_name, meta) in sorted(actions.items()):
+        def make_invoke(mname: str) -> Callable[[BaseModel, Context], Any]:
+            return lambda inp, ctx, _m=mname: getattr(tool_cls(), _m)(inp, ctx)
+
+        callback = _build_callback(
+            schema=meta.input_schema,
+            invoke=make_invoke(method_name),
+            name=cli_name.replace("-", "_"),
+            doc=meta.description,
+        )
+        subapp.command(name=cli_name, help=meta.description)(callback)
+    app.add_typer(subapp, name=tool_cls.name, help=tool_cls.description)
+
+
+discover_tools()
+load_plugins()
+for _tool_cls in all_tools().values():
+    _register_tool_in_app(_tool_cls)
+
+
+@app.command("serve", help="Start the Docent MCP server (stdio transport).")
+def serve_command() -> None:
+    """Expose all registered Docent actions as MCP tools over stdio.
+
+    Add to Claude Code's .mcp.json:
+
+    \\b
+    {
+      "mcpServers": {
+        "docent": {
+          "command": "uv",
+          "args": ["--directory", "<project-root>", "run", "docent", "serve"]
+        }
+      }
+    }
+    """
+    from docent.mcp_server import run_server
+
+    run_server()
+
+
+if __name__ == "__main__":
+    app()

docent/config/__init__.py

@@ -0,0 +1,4 @@
+from docent.config.loader import load_settings, write_setting
+from docent.config.settings import ReadingSettings, Settings
+
+__all__ = ["ReadingSettings", "Settings", "load_settings", "write_setting"]

docent/config/loader.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+
+from docent.config.settings import Settings
+from docent.utils.paths import cache_dir, config_file, data_dir, logs_dir, root_dir
+
+_DEFAULT_CONFIG_TOML = """# Docent configuration
+# Env vars (DOCENT_*) override these values.
+
+default_model = "anthropic/claude-sonnet-4-6"
+verbose = false
+no_color = false
+
+# anthropic_api_key = "sk-ant-..."
+# openai_api_key = "sk-..."
+
+[tools]
+# Per-tool settings live here. Example:
+# [tools.feynman]
+# binary_path = "/usr/local/bin/feynman"
+"""
+
+
+def _ensure_runtime_dirs() -> None:
+    for d in (root_dir(), cache_dir(), logs_dir(), data_dir()):
+        d.mkdir(parents=True, exist_ok=True)
+
+
+def _ensure_config_file() -> Path:
+    path = config_file()
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_DEFAULT_CONFIG_TOML, encoding="utf-8")
+    return path
+
+
+def load_settings() -> Settings:
+    _ensure_runtime_dirs()
+    path = _ensure_config_file()
+    with path.open("rb") as f:
+        toml_data = tomllib.load(f)
+    return Settings(**toml_data)
+
+
+def write_setting(key_path: str, value: Any) -> Path:
+    """Persist a setting into config.toml under a dotted key path.
+
+    `key_path` is a dotted path like "paper.database_dir". Sections are
+    created on demand. Existing TOML structure is preserved (round-trip
+    via tomllib + tomli_w). Returns the config-file path written.
+
+    Use for one-off `config-set` style writes; not for bulk migration.
+    """
+    if not key_path or any(not seg for seg in key_path.split(".")):
+        raise ValueError(f"Invalid setting key {key_path!r}")
+    _ensure_runtime_dirs()
+    path = _ensure_config_file()
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    cursor: dict[str, Any] = data
+    segments = key_path.split(".")
+    for seg in segments[:-1]:
+        next_cursor = cursor.get(seg)
+        if not isinstance(next_cursor, dict):
+            next_cursor = {}
+            cursor[seg] = next_cursor
+        cursor = next_cursor
+    cursor[segments[-1]] = value
+    with path.open("wb") as f:
+        tomli_w.dump(data, f)
+    return path

docent/config/settings.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+
+
+class ReadingSettings(BaseModel):
+    """First-party `reading` tool settings. Stored under `[reading]` in config.toml.
+
+    Env-overridable as `DOCENT_READING__<FIELD>` (double underscore for nesting).
+    `database_dir` accepts a path with `~`; expansion is the caller's job.
+    `database_dir` IS the Mendeley watch folder — Mendeley auto-imports anything
+    dropped here.
+    """
+
+    database_dir: Path | None = None
+    mendeley_mcp_command: list[str] | None = None  # e.g. ["uvx", "mendeley-mcp"]; None -> default in mendeley_client.
+    queue_collection: str = "Docent-Queue"  # Mendeley collection name that defines reading-queue membership.
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="DOCENT_",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    default_model: str = "anthropic/claude-sonnet-4-6"
+    verbose: bool = False
+    no_color: bool = False
+
+    anthropic_api_key: str | None = None
+    openai_api_key: str | None = None
+
+    reading: ReadingSettings = Field(default_factory=ReadingSettings)
+
+    tools: dict[str, dict[str, Any]] = Field(default_factory=dict)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (env_settings, init_settings, file_secret_settings)

docent/core/__init__.py

@@ -0,0 +1,19 @@
+from docent.core.context import Context
+from docent.core.events import ProgressEvent
+from docent.core.plugin_loader import load_plugins, run_startup_hooks
+from docent.core.registry import all_tools, get_tool, register_tool
+from docent.core.tool import Action, Tool, action, collect_actions
+
+__all__ = [
+    "Action",
+    "Context",
+    "ProgressEvent",
+    "Tool",
+    "action",
+    "all_tools",
+    "collect_actions",
+    "get_tool",
+    "load_plugins",
+    "register_tool",
+    "run_startup_hooks",
+]

docent/core/context.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from docent.config import Settings
+from docent.execution import Executor
+from docent.llm import LLMClient
+
+
+@dataclass(frozen=True)
+class Context:
+    settings: Settings
+    llm: LLMClient
+    executor: Executor

docent/core/events.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ProgressEvent(BaseModel):
+    """Streaming event yielded by long-running actions.
+
+    A generator-based action yields zero or more `ProgressEvent` values during
+    execution and `return`s its final result. The CLI dispatcher renders each
+    event live (via Rich `Progress`) and captures the result from
+    `StopIteration.value`. Tests can drive the same generator and collect
+    events into a list.
+
+    Field semantics:
+    - `phase`: short identifier for the work the action is doing now
+      (e.g. "discover", "add", "scholar"). Phase changes signal that the
+      renderer should swap to a fresh progress bar.
+    - `current` / `total`: optional 1-based progress within the phase.
+      When both are set, the renderer draws a bar; when both are None,
+      the event is rendered as an info line.
+    - `item`: short label for the current item (filename, DOI, ...).
+    - `message`: free-form text; required when there's no (current, total).
+    - `level`: severity. Errors and warnings render as console lines
+      independent of any progress bar.
+    """
+
+    phase: str
+    message: str = ""
+    current: int | None = None
+    total: int | None = None
+    item: str = ""
+    level: Literal["info", "warn", "error"] = "info"

docent/core/plugin_loader.py

@@ -0,0 +1,99 @@
+"""External plugin discovery.
+
+Search order:
+  1. src/docent/bundled_plugins/  (shipped plugins — may not exist yet, skip gracefully)
+  2. ~/.docent/plugins/           (user-installed plugins, via plugins_dir() from paths.py)
+
+Each directory is added to sys.path before importing, so plugin packages can use
+relative imports internally. Both flat *.py files and packages (dir + __init__.py)
+are supported. Names starting with _ are skipped.
+
+Broken plugins: print one-line warning to stderr, continue loading others.
+Name conflicts (plugin registers a name already taken): the registry raises ValueError,
+which is caught and printed as a warning — same skip behaviour.
+
+Startup hooks: plugins may define on_startup(context: Context) at module level.
+The loader collects them; run_startup_hooks(context) calls them all after the CLI
+creates its Context object.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Callable
+
+from docent.core.context import Context
+from docent.utils.paths import plugins_dir
+
+_STARTUP_HOOKS: list[Callable[[Context], None]] = []
+
+
+def _bundled_plugins_dir() -> Path:
+    import docent
+
+    return Path(docent.__file__).parent / "bundled_plugins"
+
+
+def _ensure_in_sys_path(directory: Path) -> None:
+    str_path = str(directory)
+    if str_path not in sys.path:
+        sys.path.insert(0, str_path)
+
+
+def _load_plugin_module(module_name: str) -> bool:
+    """Import a plugin module and collect its startup hook if present.
+
+    Returns True if loaded successfully, False if there was a recoverable error.
+    """
+    try:
+        importlib.import_module(module_name)
+    except Exception as exc:
+        print(f"Warning: failed to load plugin '{module_name}': {exc}", file=sys.stderr)
+        return False
+
+    module = sys.modules.get(module_name)
+    if module is not None and hasattr(module, "on_startup"):
+        hook = getattr(module, "on_startup")
+        if callable(hook):
+            _STARTUP_HOOKS.append(hook)
+
+    return True
+
+
+def _scan_plugin_dir(directory: Path) -> None:
+    """Scan a directory for plugin modules/packages and load them."""
+    if not directory.exists():
+        return
+
+    _ensure_in_sys_path(directory)
+
+    for entry in directory.iterdir():
+        name = entry.name
+
+        if name.startswith("_"):
+            continue
+
+        if entry.is_file() and name.endswith(".py"):
+            module_name = name[:-3]
+            _load_plugin_module(module_name)
+        elif entry.is_dir() and (entry / "__init__.py").exists():
+            module_name = name
+            _load_plugin_module(module_name)
+
+
+def load_plugins() -> None:
+    """Discover and load all external plugins."""
+    _STARTUP_HOOKS.clear()
+    _scan_plugin_dir(_bundled_plugins_dir())
+    _scan_plugin_dir(plugins_dir())
+
+
+def run_startup_hooks(context: Context) -> None:
+    """Call all collected startup hooks."""
+    for hook in _STARTUP_HOOKS:
+        try:
+            hook(context)
+        except Exception as exc:
+            print(f"Warning: startup hook failed: {exc}", file=sys.stderr)