docent-cli 1.0.0__py3-none-any.whl

docent/utils/paths.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+_ROOT_ENV = "DOCENT_HOME"
+
+
+def root_dir() -> Path:
+    import os
+
+    override = os.environ.get(_ROOT_ENV)
+    return Path(override).expanduser() if override else Path.home() / ".docent"
+
+
+def config_dir() -> Path:
+    return root_dir()
+
+
+def config_file() -> Path:
+    return config_dir() / "config.toml"
+
+
+def cache_dir() -> Path:
+    return root_dir() / "cache"
+
+
+def logs_dir() -> Path:
+    return root_dir() / "logs"
+
+
+def data_dir() -> Path:
+    return root_dir() / "data"
+
+
+def plugins_dir() -> Path:
+    return root_dir() / "plugins"

docent/utils/prompt.py

@@ -0,0 +1,63 @@
+"""Minimal interactive prompt utilities.
+
+Single function for now: `prompt_for_path`. The escape-hatch convention is the
+`DOCENT_NO_INTERACTIVE` env var - when set to anything truthy, prompts raise
+`NoInteractiveError` immediately so CI / scripted use never blocks waiting on
+stdin. Tools that prompt should always have an env-var or flag-based path that
+bypasses the prompt entirely.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from rich.prompt import Prompt
+
+from docent.ui import get_console
+
+
+_NO_INTERACTIVE_ENV = "DOCENT_NO_INTERACTIVE"
+
+
+class NoInteractiveError(RuntimeError):
+    """Raised when an interactive prompt is required but DOCENT_NO_INTERACTIVE is set.
+
+    Carries the prompt text so callers can format a clear "set X env var or
+    pass --flag" remediation hint.
+    """
+
+    def __init__(self, prompt_text: str):
+        super().__init__(
+            f"Interactive prompt required but {_NO_INTERACTIVE_ENV} is set: {prompt_text!r}"
+        )
+        self.prompt_text = prompt_text
+
+
+def _no_interactive() -> bool:
+    val = os.environ.get(_NO_INTERACTIVE_ENV, "").strip().lower()
+    return val not in ("", "0", "false", "no")
+
+
+def prompt_for_path(message: str, *, allow_create: bool = True, default: str | None = None) -> Path | None:
+    """Ask the user for a directory path, with `~` expansion.
+
+    Returns the resolved Path on success, or None if the user types 'cancel'.
+    If `allow_create` is True, the user can type 'create' to scaffold the
+    default location.
+    Raises `NoInteractiveError` if `DOCENT_NO_INTERACTIVE` is set.
+    """
+    if _no_interactive():
+        raise NoInteractiveError(message)
+
+    console = get_console()
+    raw = Prompt.ask(message, default=default or "", console=console).strip()
+    # Windows users reflexively wrap paths with spaces in quotes when pasting.
+    if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ('"', "'"):
+        raw = raw[1:-1].strip()
+    if not raw or raw.lower() == "cancel":
+        return None
+    if allow_create and raw.lower() == "create" and default:
+        path = Path(default).expanduser()
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+    return Path(raw).expanduser()

docent_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.3
+Name: docent-cli
+Version: 1.0.0
+Summary: A personal control center for grad school workflows.
+Keywords: cli,research,reading-queue,mendeley,mcp
+Author: John David K. T. Kudadjie
+Author-email: John David K. T. Kudadjie <75898705+Kudadjie@users.noreply.github.com>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Dist: litellm>=1.83.0
+Requires-Dist: mcp>=1.0,<2
+Requires-Dist: pydantic-settings>=2.14.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.24.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Kudadjie/docent
+Project-URL: Repository, https://github.com/Kudadjie/docent
+Project-URL: Bug Tracker, https://github.com/Kudadjie/docent/issues
+Description-Content-Type: text/markdown
+
+# Docent
+
+A personal CLI control center for grad-school workflows — papers, research, writing tools, subprocess wrappers — all behind a single `docent <tool>` command. Built so a web dashboard can wrap the same tool registry later without rewriting anything.
+
+> **Built with AI, Architected by a Human:** Much of the codebase for Docent was written by Claude Code (Opus 4.7) and OpenCode Go subscription models (Kimi K2.6, DeepSeek V4 Pro, Qwen 3.5 Plus, MiniMax M2.7), but the architecture was strictly human-directed — designed, planned, tested, and iterated over many sessions.
+
+## What works today
+
+- `docent --version`, `docent --help`, `docent list`, `docent info <tool>`
+- **Tool contract — two shapes:**
+  - *Single-action*: subclass `Tool`, set `input_schema`, override `run()`. CLI: `docent <tool> --flag ...`
+  - *Multi-action*: decorate methods with `@action(...)`. CLI: `docent <tool> <action> --flag ...`
+  - A tool is one or the other — registry enforces mutual exclusivity at import time.
+- **Auto-discovery**: drop a file in `src/docent/tools/`, decorate with `@register_tool`, and Typer commands generate at startup from the Pydantic input schema. No CLI edits.
+- **Context plumbing**: `context.settings` (Pydantic + `~/.docent/config.toml` + env overrides), `context.llm` (lazy litellm wrapper), `context.executor` (list-args subprocess, no shell-injection surface).
+- **`docent.learning.RunLog`**: per-namespace JSONL run-log with cap-and-roll, for tools that want a "what did I do recently" history (used by `paper`'s mutators).
+- **`reading` tool**: reading queue CRUD (`next / show / search / stats / remove / edit / done / start / export`); `add` (guidance mode — ingestion goes through Mendeley); `sync-from-mendeley` (reconciles the configured Mendeley collection into the local queue, overlays fresh metadata on display); `sync-pull` (Unpaywall OA download); `sync-status`; `move-up / move-down / move-to`; deadline notifications at startup; `config-show / config-set`; `queue-clear`. Mendeley is the source of truth for title/authors/year/doi — the reading tool is a thin workflow layer on top.
+- **`ReadingQueueStore`**: persistence seam in `reading_store.py`. Actions mutate queue state through the store, never by reaching into JSON directly.
+- **`MendeleyCache`**: read-through file-backed cache (5-min TTL) used by `next / show / search` to overlay live Mendeley metadata. Degrades gracefully to queue snapshot on auth/transport failure.
+- Themed Rich console singleton; tools never touch it directly (they return typed data; CLI renders).
+
+## Install
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.11+.
+
+```bash
+uv sync
+uv run docent --version
+```
+
+For a global install once you want `docent` on your PATH:
+
+```bash
+uv tool install .
+docent --version
+```
+
+## Architecture
+
+See [`Docent_Architecture.md`](Docent_Architecture.md) for the full design. The short version:
+
+- **Tool registry** — tools self-register via `@register_tool` at import time. Registry stores the class, not an instance, so nothing runs until the tool is actually invoked.
+- **Context object** — frozen dataclass passed to every tool. Provides `settings`, `llm` (lazy litellm), and `executor` (subprocess wrapper).
+- **UI / logic boundary** — tools return typed Pydantic data. They never import `docent.ui` and never touch Rich. The CLI renders; the future dashboard will serialize the same data to JSON.
+- **Plugin system** — drop a file in `src/docent/tools/`, decorate with `@register_tool`, and Typer commands generate at startup. No CLI edits needed.
+
+## Tools
+
+### `reading` — Reading Queue
+
+Manages your academic reading queue and syncs with Mendeley.
+
+**Workflow:** Drop a PDF in your `database_dir` → Mendeley auto-imports it → drag it into your `Docent-Queue` collection in Mendeley → run `docent reading sync-from-mendeley`. The category of each entry is automatically detected from Mendeley sub-collections (e.g. a paper in `Docent-Queue/TestCourse701/ParticularTopic` gets `category="TestCourse701/ParticularTopic"`).
+
+**Queue management**
+
+| Command | Description |
+|---|---|
+| `docent reading next` | Show the next paper to read (lowest order number) |
+| `docent reading next --course-name CES701` | Next paper for a specific course |
+| `docent reading show <id>` | Show full details for one entry |
+| `docent reading search <query>` | Search by title, authors, notes, tags, or id |
+| `docent reading stats` | Counts by status, category, and course |
+| `docent reading export` | Export queue as JSON (default) or Markdown table |
+| `docent reading export --format markdown --status queued` | Filtered export, sorted by reading order |
+
+**Status transitions**
+
+| Command | Description |
+|---|---|
+| `docent reading start <id>` | Mark as currently reading (stamps `started` timestamp) |
+| `docent reading done <id>` | Mark as finished (stamps `finished` timestamp) |
+| `docent reading remove <id>` | Remove entry from queue |
+
+**Editing**
+
+| Command | Description |
+|---|---|
+| `docent reading edit <id> --order 1` | Set reading priority (1 = read first) |
+| `docent reading set-deadline <id> --deadline 2026-06-15` | Set a reading deadline |
+| `docent reading set-deadline <id> --deadline ''` | Clear a deadline |
+| `docent reading edit <id> --notes "Key paper for lit review"` | Add notes |
+| `docent reading edit <id> --tags tag1 tag2` | Set tags |
+| `docent reading edit <id> --type book_chapter` | Set entry type (paper / book / book_chapter) |
+| `docent reading move-up <id>` | Move one position earlier |
+| `docent reading move-down <id>` | Move one position later |
+| `docent reading move-to <id> --position 3` | Move to a specific position |
+
+**Deadlines:** Set via `set-deadline --deadline YYYY-MM-DD`. Docent prints a startup warning for entries due within 3 days or overdue — once per calendar day.
+
+**Entry types:** Automatically detected from Mendeley document type on sync (`journal_article` → paper, `book` → book, `book_section` → book chapter). Override with `edit --type book_chapter`.
+
+**Mendeley sync**
+
+| Command | Description |
+|---|---|
+| `docent reading sync-from-mendeley` | Pull from your Mendeley Docent-Queue collection |
+| `docent reading sync-from-mendeley --dry-run` | Preview changes without writing |
+| `docent reading sync-status` | Report queue size and PDFs in database_dir |
+
+**Configuration**
+
+| Command | Description |
+|---|---|
+| `docent reading config-show` | Show current reading settings |
+| `docent reading config-set database_dir ~/path/to/Papers` | Set the PDF database folder |
+| `docent reading config-set queue_collection "Docent-Queue"` | Set the Mendeley collection name |
+
+**Other**
+
+| Command | Description |
+|---|---|
+| `docent reading queue-clear --yes` | Wipe the entire queue (irreversible) |
+
+## Adding a tool
+
+Single-action tools are the simplest shape:
+
+```python
+# src/docent/tools/echo.py
+from pydantic import BaseModel, Field
+from docent.core import Context, Tool, register_tool
+
+
+class EchoInputs(BaseModel):
+    msg: str = Field(..., description="Message to echo.")
+    count: int = Field(1, description="Times to repeat.")
+
+
+@register_tool
+class Echo(Tool):
+    name = "echo"
+    description = "Repeat a message N times."
+    category = "demo"
+    input_schema = EchoInputs
+
+    def run(self, inputs: EchoInputs, context: Context) -> str:
+        return (inputs.msg + " ") * inputs.count
+```
+
+Then `docent echo --msg hi --count 3` just works. No CLI edits, no registration code — the decorator is enough.
+
+For tools with several related operations on shared state (a reading queue, a research notebook, a browser session), use the multi-action shape — decorate methods with `@action(...)` instead of overriding `run()`. Each action gets its own Pydantic input schema and becomes `docent <tool> <action> --flag ...`. See `src/docent/tools/reading.py` for the reference implementation.
+
+## Why
+
+I have a pile of Claude Code skills I actually use (research-to-notebook, paper-pipeline, feynman wrappers, literature-review, etc.) but they only work inside a Claude session. Docent is the terminal-first home for the same workflows — scriptable, pipeable, cron-able, and eventually a dashboard. MCP is not a replacement; Docent can later expose itself *through* MCP, but that's a late-stage adapter, not the core.

docent_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+docent/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+docent/bundled_plugins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docent/bundled_plugins/reading/__init__.py,sha256=R8a5FCFNmFsMeoylRJWr9-xelI5gRtZlqM0m-OBTxg4,52063
+docent/bundled_plugins/reading/mendeley_cache.py,sha256=x8ROHcwXrZNvAQVHM8Btw1clRCNURfGNdzlco9Q68xY,6943
+docent/bundled_plugins/reading/mendeley_client.py,sha256=d9nwWZJEOnk4D3M0YELqi1CMZYK8G_Hqr4WuWzZExt8,5115
+docent/bundled_plugins/reading/reading_notify.py,sha256=0U8e6uHtciO03A9W5FG28w8sTp7maQ7VEjUfAZMGEvs,2742
+docent/bundled_plugins/reading/reading_store.py,sha256=W-Lk_uMJjsUk2OHAD1vnqTWwbsUuK1DoOIXRyPxuqOA,3487
+docent/cli.py,sha256=Xv09cDfrgoF07WBw1WAhiuGgnVzx-144i32Motv9hCM,10264
+docent/config/__init__.py,sha256=T6T1Ih6Sixm5TclvD1l0Gxl03BgMPttmq6kBmn6nIAc,200
+docent/config/loader.py,sha256=oyibLSWHAMSYbLEpeee-qNK1xyB3d7cdAXVLtF7WLpA,2215
+docent/config/settings.py,sha256=n_QOHOsVuK627zN8dNIdZw4nLXgWkn1RPsy_GeYUtjo,1800
+docent/core/__init__.py,sha256=Fck8Va27z3IH_QHf2IM1H4cbZc2EkErC_hEm0lVjEJo,503
+docent/core/context.py,sha256=SU-gUI_dtUOy-NmvocjyRtGo86kKT31rLq-WtVf0X60,283
+docent/core/events.py,sha256=siue9SjP5_zISiPgqxFISrglNxMFpB_oESyHAVeehlk,1341
+docent/core/plugin_loader.py,sha256=THcTl63XDYaKjqrMxNgdPN10_jjr_RGR2N8heJdirTY,3093
+docent/core/registry.py,sha256=4Y9sAEpqz44hBiY92NujppQHPFx95yXy172yijo9vUg,3224
+docent/core/tool.py,sha256=DdN6TmfDluf402Do-po8MormXjU83aAZq8IeQC54Lbk,2889
+docent/execution/__init__.py,sha256=5k7V2CJUj7HBraqqX8Igecn3PWxHYMFa6c-SFuEZBz4,151
+docent/execution/executor.py,sha256=EA8ffyGuFcUFeo5ca-NKahCFeKvr0WsOnpr7K5cWZeY,1824
+docent/learning/__init__.py,sha256=t2Jd6wNf3-kQJ6tzRPtJFI63d9nxNhhgYZonwGWqlAI,65
+docent/learning/run_log.py,sha256=A5JTSGTp9VbaesQ0CpEWX0T4L7-pqbrF3VnOreKUNGM,2479
+docent/llm/__init__.py,sha256=I7267-g94nMCUqT1J7mRK1mVTJvIGJJ6mlr2_NZkVKQ,93
+docent/llm/client.py,sha256=O2wdGVAYNvW1PzSiHRAnuRHok1gHS_5TiuAOj1cVemI,1845
+docent/mcp_server.py,sha256=MvNH7FD8RUmBNBv9OJtSPsgzUP8NU8UyRZcBazSdBI4,6141
+docent/tools/__init__.py,sha256=y3OIGjYq6aazeWsyqFV04xYvH8rXPlotVO8-ZR9hRgM,516
+docent/ui/__init__.py,sha256=yhiKUHzkiXZiZAP0NjfoWaS7tdNQ6lk4JXUO_KCj-Fg,109
+docent/ui/console.py,sha256=1-LYrArKwnMQ5kNYAhd9T55rGODGusQUf3b-iH5LS_k,663
+docent/ui/theme.py,sha256=UrAsK3ltEicQW7pZ2SMVTC4wAxl15Pgp1X1YHRV5Ei8,338
+docent/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docent/utils/paths.py,sha256=-4JW3k7Er8uj2auM6b-vkYiESmlc37E61JmPlYykZhY,605
+docent/utils/prompt.py,sha256=5uWS3WYOU-fS8X90D5uZTrYd0jrHjetTntPbsJepRFg,2226
+docent_cli-1.0.0.dist-info/WHEEL,sha256=iCTolw4aw2dP3yfM-EQCGTDsFCXL_ymmbYnBRVH7plA,81
+docent_cli-1.0.0.dist-info/entry_points.txt,sha256=BXFGTBbAdk3EyaVPnfyMYwXUc4NKcRN3KzM1Ad99a6M,43
+docent_cli-1.0.0.dist-info/METADATA,sha256=GF1ifzlJx8RUvOHuV_FXSJfyU2sHMfNCmkL4Zg7Vae8,9404
+docent_cli-1.0.0.dist-info/RECORD,,

docent_cli-1.0.0.dist-info/WHEEL

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

docent_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+docent = docent.cli:app
+