paper-plane-x-cli 0.1.0__py3-none-any.whl

paper_plane_x_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Paper Plane X CLI package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

paper_plane_x_cli/cli/__init__.py

@@ -0,0 +1,89 @@
+"""Paper Plane X HTTP CLI for external agent tools."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import httpx as httpx
+import typer
+
+from paper_plane_x_cli.cli.context import context_app
+from paper_plane_x_cli.cli.files import files_app
+from paper_plane_x_cli.cli.librarian import librarian_app
+from paper_plane_x_cli.cli.paper import paper_app
+from paper_plane_x_cli.cli.paper_note import paper_note_app
+from paper_plane_x_cli.cli.pdf import pdf_app
+from paper_plane_x_cli.cli.project import project_app
+from paper_plane_x_cli.cli.skills import skills_app
+from paper_plane_x_cli.cli.utils import DEFAULT_BASE_URL, load_context
+
+GLOBAL_CONTEXT_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+GLOBAL_CONTEXT_PATH = GLOBAL_CONTEXT_DIR / "paper-plane-x" / "context.json"
+LOCAL_CONTEXT_PATH = Path.cwd() / ".paper-plane-x" / "context.json"
+
+
+def resolve_context(
+    base_url: str | None = None,
+    project_id: str | None = None,
+) -> dict[str, str | None]:
+    global_ctx = load_context(GLOBAL_CONTEXT_PATH)
+    local_ctx = load_context(LOCAL_CONTEXT_PATH)
+    merged = {**global_ctx, **local_ctx}
+    resolved_base_url = (
+        base_url
+        or os.environ.get("PPX_BASE_URL")
+        or merged.get("base_url")
+        or DEFAULT_BASE_URL
+    )
+    resolved_project_id = (
+        project_id or os.environ.get("PPX_PROJECT_ID") or merged.get("project_id")
+    )
+    return {
+        "base_url": resolved_base_url.rstrip("/"),
+        "project_id": resolved_project_id,
+    }
+
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help=(
+        "Paper Plane X HTTP CLI. All commands call a running Paper Plane X "
+        "FastAPI server and print JSON for external agents."
+    ),
+)
+
+
+@app.callback()
+def callback(
+    ctx: typer.Context,
+    base_url: Annotated[
+        str | None,
+        typer.Option(
+            "--base-url",
+            help="Override API base URL, e.g. http://127.0.0.1:8000/api/v1.",
+        ),
+    ] = None,
+    project_id: Annotated[
+        str | None,
+        typer.Option("--project-id", help="Override current Paper Plane X project ID."),
+    ] = None,
+) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["ctx"] = resolve_context(base_url=base_url, project_id=project_id)
+
+
+app.add_typer(context_app, name="context")
+app.add_typer(project_app, name="project")
+app.add_typer(pdf_app, name="pdf")
+app.add_typer(librarian_app, name="librarian")
+app.add_typer(files_app, name="files")
+app.add_typer(paper_app, name="paper")
+app.add_typer(paper_note_app, name="paper-note")
+app.add_typer(skills_app, name="skills")
+
+
+if __name__ == "__main__":
+    app()

paper_plane_x_cli/cli/context.py

@@ -0,0 +1,72 @@
+"""Context management commands for the Paper Plane X CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from paper_plane_x_cli.cli.utils import (
+    GLOBAL_CONTEXT_PATH,
+    LOCAL_CONTEXT_PATH,
+    load_context,
+    print_json,
+    save_context,
+)
+
+context_app = typer.Typer(
+    no_args_is_help=True,
+    help="Show or save local CLI context such as API base URL and project ID.",
+)
+
+
+@context_app.command("show", help="Print resolved CLI context as JSON.")
+def context_show(ctx: typer.Context) -> None:
+    global_ctx = load_context(GLOBAL_CONTEXT_PATH)
+    local_ctx = load_context(LOCAL_CONTEXT_PATH)
+    merged = {**global_ctx, **local_ctx}
+    resolved = ctx.obj["ctx"]
+    print_json(
+        {
+            "resolved": resolved,
+            "global": global_ctx or None,
+            "local": local_ctx or None,
+            "merged": merged or None,
+        }
+    )
+
+
+@context_app.command(
+    "set",
+    help=f"Save context to {GLOBAL_CONTEXT_PATH} (default) or {LOCAL_CONTEXT_PATH} (--local).",
+)
+def context_set(
+    set_base_url: Annotated[
+        str | None,
+        typer.Option(
+            "--base-url",
+            help="API base URL to save, e.g. http://127.0.0.1:8000/api/v1.",
+        ),
+    ] = None,
+    set_project_id: Annotated[
+        str | None,
+        typer.Option(
+            "--project-id", help="Project ID to save for project-scoped commands."
+        ),
+    ] = None,
+    local: Annotated[
+        bool,
+        typer.Option(
+            "--local",
+            help="Write to the local context file in the current directory instead of the global one.",
+        ),
+    ] = False,
+) -> None:
+    path = LOCAL_CONTEXT_PATH if local else GLOBAL_CONTEXT_PATH
+    data = load_context(path)
+    if set_base_url is not None:
+        data["base_url"] = set_base_url.rstrip("/")
+    if set_project_id is not None:
+        data["project_id"] = set_project_id
+    save_context(data, path)
+    print_json(data)

paper_plane_x_cli/cli/files.py

@@ -0,0 +1,282 @@
+"""Project sandbox file commands for the Paper Plane X CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from paper_plane_x_cli.cli.utils import print_json, request, require_project_id
+
+files_app = typer.Typer(
+    no_args_is_help=True,
+    help="Read, write, upload, patch, and delete project sandbox files.",
+)
+
+
+@files_app.command("list", help="List files and directories in the project sandbox.")
+def files_list(
+    ctx: typer.Context,
+    dir: Annotated[str, typer.Option("--dir", help="Sandbox directory to list.")] = "/",
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request("GET", prefix, ctx=ctx_dict, params={"dir_path": dir})
+    print_json(payload)
+
+
+@files_app.command("read", help="Read a project sandbox text file.")
+def files_read(
+    ctx: typer.Context,
+    path: Annotated[
+        str,
+        typer.Option("--path", help="Sandbox file path, e.g. /notes/idea.md."),
+    ],
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "GET", f"{prefix}/content", ctx=ctx_dict, params={"file_path": path}
+    )
+    print_json(payload)
+
+
+@files_app.command("lines", help="Read a 1-based inclusive line range from a file.")
+def files_lines(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox file path.")],
+    start_line: Annotated[
+        int, typer.Option("--start-line", help="First line, 1-based.")
+    ],
+    end_line: Annotated[
+        int | None,
+        typer.Option(
+            "--end-line", help="Last line, inclusive. Defaults to start line."
+        ),
+    ] = None,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "GET",
+        f"{prefix}/lines",
+        ctx=ctx_dict,
+        params={
+            "file_path": path,
+            "start_line": start_line,
+            "end_line": end_line,
+        },
+    )
+    print_json(payload)
+
+
+@files_app.command("find", help="Find text occurrences in a project sandbox file.")
+def files_find(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox file path.")],
+    query: Annotated[str, typer.Option("--query", help="Text to search for.")],
+    case_sensitive: Annotated[
+        bool,
+        typer.Option("--case-sensitive", help="Use case-sensitive matching."),
+    ] = False,
+    max_matches: Annotated[
+        int,
+        typer.Option("--max-matches", help="Maximum number of matches to return."),
+    ] = 20,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "GET",
+        f"{prefix}/find",
+        ctx=ctx_dict,
+        params={
+            "file_path": path,
+            "query": query,
+            "case_sensitive": case_sensitive,
+            "max_matches": max_matches,
+        },
+    )
+    print_json(payload)
+
+
+@files_app.command("write", help="Write or overwrite a project sandbox text file.")
+def files_write(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox destination path.")],
+    content: Annotated[
+        str, typer.Option("--content", help="Full text content to write.")
+    ],
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "PUT",
+        f"{prefix}/content",
+        ctx=ctx_dict,
+        json_body={"file_path": path, "content": content},
+    )
+    print_json(payload)
+
+
+@files_app.command("upload", help="Upload a local file into the project sandbox.")
+def files_upload(
+    ctx: typer.Context,
+    source: Annotated[
+        Path,
+        typer.Option(
+            "--source",
+            exists=True,
+            dir_okay=False,
+            help="Local file to upload.",
+        ),
+    ],
+    path: Annotated[
+        str | None,
+        typer.Option(
+            "--path",
+            help="Sandbox destination path. Defaults to /<source filename>.",
+        ),
+    ] = None,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    target_path = path or f"/{source.name}"
+    prefix = f"/projects/{project_id}/files"
+    with source.open("rb") as file_obj:
+        payload = request(
+            "POST",
+            f"{prefix}/upload",
+            ctx=ctx_dict,
+            data={"file_path": target_path},
+            files={"file": (source.name, file_obj)},
+        )
+    print_json(payload)
+
+
+@files_app.command("replace-lines", help="Replace a 1-based inclusive line range.")
+def files_replace_lines(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox file path.")],
+    start_line: Annotated[
+        int, typer.Option("--start-line", help="First line to replace.")
+    ],
+    end_line: Annotated[int, typer.Option("--end-line", help="Last line to replace.")],
+    new_text: Annotated[str, typer.Option("--new-text", help="Replacement text.")],
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "PATCH",
+        f"{prefix}/lines",
+        ctx=ctx_dict,
+        json_body={
+            "file_path": path,
+            "start_line": start_line,
+            "end_line": end_line,
+            "new_text": new_text,
+        },
+    )
+    print_json(payload)
+
+
+@files_app.command("replace-text", help="Replace exact text in a project sandbox file.")
+def files_replace_text(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox file path.")],
+    old_text: Annotated[str, typer.Option("--old-text", help="Exact text to replace.")],
+    new_text: Annotated[str, typer.Option("--new-text", help="Replacement text.")],
+    replace_all: Annotated[
+        bool,
+        typer.Option("--replace-all", help="Replace all occurrences instead of one."),
+    ] = False,
+    expected_occurrences: Annotated[
+        int,
+        typer.Option(
+            "--expected-occurrences",
+            help="Required occurrence count before replacement proceeds.",
+        ),
+    ] = 1,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "PATCH",
+        f"{prefix}/text",
+        ctx=ctx_dict,
+        json_body={
+            "file_path": path,
+            "old_text": old_text,
+            "new_text": new_text,
+            "replace_all": replace_all,
+            "expected_occurrences": expected_occurrences,
+        },
+    )
+    print_json(payload)
+
+
+@files_app.command("patch", help="Patch a file relative to an exact anchor text.")
+def files_patch(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox file path.")],
+    action: Annotated[
+        str,
+        typer.Option(
+            "--action",
+            help="Patch action: replace, insert_before, insert_after, or delete.",
+        ),
+    ],
+    anchor_text: Annotated[
+        str,
+        typer.Option("--anchor-text", help="Exact anchor text to locate."),
+    ],
+    content: Annotated[
+        str,
+        typer.Option("--content", help="Content for replace/insert actions."),
+    ] = "",
+    expected_occurrences: Annotated[
+        int,
+        typer.Option(
+            "--expected-occurrences",
+            help="Required anchor occurrence count before patch proceeds.",
+        ),
+    ] = 1,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "PATCH",
+        f"{prefix}/patch",
+        ctx=ctx_dict,
+        json_body={
+            "file_path": path,
+            "action": action,
+            "anchor_text": anchor_text,
+            "content": content,
+            "expected_occurrences": expected_occurrences,
+        },
+    )
+    print_json(payload)
+
+
+@files_app.command("delete", help="Delete a project sandbox file or empty directory.")
+def files_delete(
+    ctx: typer.Context,
+    path: Annotated[str, typer.Option("--path", help="Sandbox path to delete.")],
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    project_id = require_project_id(ctx_dict)
+    prefix = f"/projects/{project_id}/files"
+    payload = request(
+        "DELETE", f"{prefix}/content", ctx=ctx_dict, params={"file_path": path}
+    )
+    print_json(payload)

paper_plane_x_cli/cli/librarian.py

@@ -0,0 +1,108 @@
+"""Librarian search and deep-dive commands for the Paper Plane X CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from paper_plane_x_cli.cli.utils import print_json, request, split_csv
+
+librarian_app = typer.Typer(
+    no_args_is_help=True,
+    help="Search, compare, and deep-dive papers through the Librarian API.",
+)
+
+
+@librarian_app.command(
+    "search",
+    help="Search project papers with the Librarian query expression DSL.",
+)
+def librarian_search(
+    ctx: typer.Context,
+    query_expr: Annotated[
+        str,
+        typer.Option(
+            "--query-expr", help='DSL query, e.g. "(meta.title CONTAINS transformer)".'
+        ),
+    ],
+    limit: Annotated[
+        int, typer.Option("--limit", help="Maximum number of papers.")
+    ] = 20,
+    offset: Annotated[int, typer.Option("--offset", help="Pagination offset.")] = 0,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    payload = request(
+        "POST",
+        "/librarian/search",
+        ctx=ctx_dict,
+        json_body={
+            "project_id": ctx_dict.get("project_id"),
+            "query_expr": query_expr,
+            "limit": limit,
+            "offset": offset,
+        },
+    )
+    print_json(payload)
+
+
+@librarian_app.command(
+    "matrix",
+    help="Fetch structured field paths for one or more papers.",
+)
+def librarian_matrix(
+    ctx: typer.Context,
+    paper_ids: Annotated[
+        str,
+        typer.Option("--paper-ids", help="Comma-separated paper IDs, e.g. p1,p2."),
+    ],
+    field_paths: Annotated[
+        str,
+        typer.Option(
+            "--field-paths",
+            help="Comma-separated field paths, e.g. meta.title,quick_scan.verdict.",
+        ),
+    ],
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    payload = request(
+        "POST",
+        "/librarian/matrix",
+        ctx=ctx_dict,
+        json_body={
+            "paper_ids": split_csv(paper_ids),
+            "field_paths": split_csv(field_paths),
+        },
+    )
+    print_json(payload)
+
+
+@librarian_app.command(
+    "deep-dive",
+    help="Ask a focused question about a single paper.",
+)
+def librarian_deep_dive(
+    ctx: typer.Context,
+    paper_id: Annotated[str, typer.Option("--paper-id", help="Paper ID to inspect.")],
+    question: Annotated[
+        str,
+        typer.Option("--question", help="Focused question for the Deep Diver agent."),
+    ],
+    timeout: Annotated[
+        int,
+        typer.Option(
+            "--timeout",
+            help="Timeout in seconds for the Deep Diver agent to answer the question.",
+            min=1,
+        ),
+    ] = 600,
+) -> None:
+    ctx_dict = ctx.obj["ctx"]
+    payload = request(
+        "POST",
+        "/librarian/deep-dive",
+        ctx=ctx_dict,
+        json_body={"paper_id": paper_id, "question": question},
+        timeout=timeout,
+    )
+    print_json(payload)

paper_plane_x_cli/cli/paper.py

@@ -0,0 +1,58 @@
+"""Paper resource commands for the Paper Plane X CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from paper_plane_x_cli.cli.utils import fail, print_json, request_bytes
+
+paper_app = typer.Typer(
+    no_args_is_help=True,
+    help="Access Paper Plane X paper resources.",
+)
+
+
+@paper_app.command("markdown", help="Download a paper's parsed Markdown text.")
+def paper_markdown(
+    ctx: typer.Context,
+    paper_id: Annotated[str, typer.Option("--paper-id", help="Paper ID.")],
+    save_dir: Annotated[
+        Path,
+        typer.Option(
+            "--save-dir",
+            help="Directory where the Markdown file is written.",
+        ),
+    ],
+    output_md_name: Annotated[
+        str | None,
+        typer.Option(
+            "--output-md-name",
+            help="Markdown filename. Defaults to <paper-id>.md.",
+        ),
+    ] = None,
+) -> None:
+    md_name = output_md_name or f"{paper_id}.md"
+    name_path = Path(md_name)
+    if name_path.name != md_name or name_path.suffix.lower() != ".md":
+        fail("--output-md-name must be a single .md filename")
+
+    content = request_bytes(
+        "GET",
+        f"/papers/{paper_id}/markdown",
+        ctx.obj["ctx"],
+    )
+
+    save_dir.mkdir(parents=True, exist_ok=True)
+    md_path = save_dir / md_name
+    md_path.write_bytes(content)
+
+    print_json(
+        {
+            "paper_id": paper_id,
+            "md_path": str(md_path),
+            "bytes_written": len(content),
+        }
+    )

paper_plane_x_cli/cli/paper_note.py

@@ -0,0 +1,45 @@
+"""Paper-level agent note commands for the Paper Plane X CLI."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from paper_plane_x_cli.cli.utils import print_json, request
+
+paper_note_app = typer.Typer(
+    no_args_is_help=True,
+    help="Get, write, or delete paper-level agent notes.",
+)
+
+
+@paper_note_app.command("get", help="Read the agent note for a paper.")
+def paper_note_get(
+    ctx: typer.Context,
+    paper_id: Annotated[str, typer.Option("--paper-id", help="Paper ID.")],
+) -> None:
+    path = f"/papers/{paper_id}/agent-note"
+    payload = request("GET", path, ctx=ctx.obj["ctx"])
+    print_json(payload)
+
+
+@paper_note_app.command("write", help="Write or overwrite the agent note for a paper.")
+def paper_note_write(
+    ctx: typer.Context,
+    paper_id: Annotated[str, typer.Option("--paper-id", help="Paper ID.")],
+    content: Annotated[str, typer.Option("--content", help="Full note content.")],
+) -> None:
+    path = f"/papers/{paper_id}/agent-note"
+    payload = request("PUT", path, ctx=ctx.obj["ctx"], json_body={"content": content})
+    print_json(payload)
+
+
+@paper_note_app.command("delete", help="Delete the agent note for a paper.")
+def paper_note_delete(
+    ctx: typer.Context,
+    paper_id: Annotated[str, typer.Option("--paper-id", help="Paper ID.")],
+) -> None:
+    path = f"/papers/{paper_id}/agent-note"
+    payload = request("DELETE", path, ctx=ctx.obj["ctx"])
+    print_json(payload)