llm-api-scope 0.7.0__tar.gz → 0.9.0__tar.gz

llm_api_scope-0.9.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: llm-api-scope
+Version: 0.9.0
+Summary: read and cache structured documents from remote for LLM agents
+Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 D7x7z49
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/D7x7z49/llm-api-scope
+Project-URL: Repository, https://github.com/D7x7z49/llm-api-scope.git
+Project-URL: Issues, https://github.com/D7x7z49/llm-api-scope/issues
+Keywords: agent-tool,document-reader,openapi,specification
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Requires-Python: <4.0,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.26.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: httpx>=0.28.1
+Dynamic: license-file
+
+# LLM API Scope (apiscope)
+
+a tool for LLM agents to read and cache structured documents from remote.
+
+## install
+
+use [pipx](https://github.com/pypa/pipx) for isolated installation:
+
+```bash
+pipx install llm-api-scope
+```
+
+## how it works
+
+apiscope has two ideas: a registered source, and a tree you navigate by address.
+text is the default output; `--json` prints the data layer instead.
+
+### manage
+
+`apiscope add` registers a source with a name, a location, and a type.
+`apiscope remove` deletes it.
+`apiscope list` shows what is registered, filtered by type.
+
+five document types share one command surface:
+
+- `filesystem` reads a local file or directory
+- `repo` reads a directory inside a [git](https://git-scm.com) repository
+- `openapi` reads an [OpenAPI](https://www.openapis.org) specification
+- `rfc` reads an [IETF](https://www.ietf.org) document
+- `llmstxt` reads a [site index](https://llmstxt.org) that lists documentation pages
+
+```bash
+apiscope add docs https://example.test/docs/llms.txt --type llmstxt
+apiscope list all
+```
+
+### use
+
+`apiscope sync` fetches sources into a local cache.
+`apiscope view` shows the cached structure, and `apiscope read` reads one node.
+
+view and read share the same address: a source name plus an optional route.
+
+```bash
+apiscope sync all
+apiscope view docs
+apiscope read docs 1.2
+```
+
+every source projects into one tree.
+an ordinary node has children; a leaf has none.
+a view line is `- [index] key: description`, where the index is a tree address.
+an index from view always works with read.
+
+### skill
+
+`apiscope skill` prints or installs a combined command reference and strategy guide for AI agents.
+run `apiscope skill show` to print it, or `apiscope skill install` to install it under `~/.agents/skills/apiscope`.
+
+agents read this once at onboarding instead of running `--help` repeatedly.
+
+### configuration
+
+apiscope reads three configuration layers in order.
+the global file is `~/.apiscope/config.json`.
+the project file is `.apiscope/config.json`, and the local file is `.apiscope/local.json`.
+`--global` uses the global layer only and skips project discovery.
+
+the public setting holds the default source ttl in days.
+the local setting holds the proxy.
+
+```json
+{
+  "setting": {
+    "public": {"doc_ttl": 7},
+    "local": {"proxy": "http://proxy.example.test:8080"}
+  }
+}
+```
+
+the cache lives in the app directory of the selected layer, and the rest of its rules sit under `## commands`.
+
+## commands
+
+### add
+
+register a source:
+
+```bash
+apiscope add <name> <source> --type <type> [--ttl <days>]
+```
+
+### remove
+
+delete a source:
+
+```bash
+apiscope remove <name>
+```
+
+### list
+
+list registered sources:
+
+```bash
+apiscope list <selector> [--limit <n>] [--offset <n>]
+```
+
+the selector is one of all, filesystem, repo, openapi, rfc, or llmstxt.
+
+### sync
+
+fetch sources into the cache:
+
+```bash
+apiscope sync <selector> [<name>] [--force]
+```
+
+the selector is the same as in list, and the optional name narrows the range to one source.
+a source refreshes when its cache is older than its ttl, and `--force` ignores the ttl.
+`repo` clones with shallow depth, a blobless filter, and sparse checkout.
+`llmstxt` reads the index page, downloads the pages it lists, and skips a failed page.
+
+### view
+
+show the cached structure of an address:
+
+```bash
+apiscope view <address> [--depth <n>]
+```
+
+depth caps the levels below the scope; the default is unlimited.
+
+### read
+
+read one node:
+
+```bash
+apiscope read <address> [<index>]
+```
+
+the index is optional when the address already points at a leaf.
+
+### skill
+
+print or install the agent skill:
+
+```bash
+apiscope skill show
+apiscope skill install [<target>]
+```
+
+install defaults to `~/.agents/skills/apiscope`.
+
+## future
+
+- read academic papers from arxiv
+- more formal document formats as the need arises
+
+## license
+
+MIT

llm_api_scope-0.9.0/README.md

@@ -0,0 +1,162 @@
+# LLM API Scope (apiscope)
+
+a tool for LLM agents to read and cache structured documents from remote.
+
+## install
+
+use [pipx](https://github.com/pypa/pipx) for isolated installation:
+
+```bash
+pipx install llm-api-scope
+```
+
+## how it works
+
+apiscope has two ideas: a registered source, and a tree you navigate by address.
+text is the default output; `--json` prints the data layer instead.
+
+### manage
+
+`apiscope add` registers a source with a name, a location, and a type.
+`apiscope remove` deletes it.
+`apiscope list` shows what is registered, filtered by type.
+
+five document types share one command surface:
+
+- `filesystem` reads a local file or directory
+- `repo` reads a directory inside a [git](https://git-scm.com) repository
+- `openapi` reads an [OpenAPI](https://www.openapis.org) specification
+- `rfc` reads an [IETF](https://www.ietf.org) document
+- `llmstxt` reads a [site index](https://llmstxt.org) that lists documentation pages
+
+```bash
+apiscope add docs https://example.test/docs/llms.txt --type llmstxt
+apiscope list all
+```
+
+### use
+
+`apiscope sync` fetches sources into a local cache.
+`apiscope view` shows the cached structure, and `apiscope read` reads one node.
+
+view and read share the same address: a source name plus an optional route.
+
+```bash
+apiscope sync all
+apiscope view docs
+apiscope read docs 1.2
+```
+
+every source projects into one tree.
+an ordinary node has children; a leaf has none.
+a view line is `- [index] key: description`, where the index is a tree address.
+an index from view always works with read.
+
+### skill
+
+`apiscope skill` prints or installs a combined command reference and strategy guide for AI agents.
+run `apiscope skill show` to print it, or `apiscope skill install` to install it under `~/.agents/skills/apiscope`.
+
+agents read this once at onboarding instead of running `--help` repeatedly.
+
+### configuration
+
+apiscope reads three configuration layers in order.
+the global file is `~/.apiscope/config.json`.
+the project file is `.apiscope/config.json`, and the local file is `.apiscope/local.json`.
+`--global` uses the global layer only and skips project discovery.
+
+the public setting holds the default source ttl in days.
+the local setting holds the proxy.
+
+```json
+{
+  "setting": {
+    "public": {"doc_ttl": 7},
+    "local": {"proxy": "http://proxy.example.test:8080"}
+  }
+}
+```
+
+the cache lives in the app directory of the selected layer, and the rest of its rules sit under `## commands`.
+
+## commands
+
+### add
+
+register a source:
+
+```bash
+apiscope add <name> <source> --type <type> [--ttl <days>]
+```
+
+### remove
+
+delete a source:
+
+```bash
+apiscope remove <name>
+```
+
+### list
+
+list registered sources:
+
+```bash
+apiscope list <selector> [--limit <n>] [--offset <n>]
+```
+
+the selector is one of all, filesystem, repo, openapi, rfc, or llmstxt.
+
+### sync
+
+fetch sources into the cache:
+
+```bash
+apiscope sync <selector> [<name>] [--force]
+```
+
+the selector is the same as in list, and the optional name narrows the range to one source.
+a source refreshes when its cache is older than its ttl, and `--force` ignores the ttl.
+`repo` clones with shallow depth, a blobless filter, and sparse checkout.
+`llmstxt` reads the index page, downloads the pages it lists, and skips a failed page.
+
+### view
+
+show the cached structure of an address:
+
+```bash
+apiscope view <address> [--depth <n>]
+```
+
+depth caps the levels below the scope; the default is unlimited.
+
+### read
+
+read one node:
+
+```bash
+apiscope read <address> [<index>]
+```
+
+the index is optional when the address already points at a leaf.
+
+### skill
+
+print or install the agent skill:
+
+```bash
+apiscope skill show
+apiscope skill install [<target>]
+```
+
+install defaults to `~/.agents/skills/apiscope`.
+
+## future
+
+- read academic papers from arxiv
+- more formal document formats as the need arises
+
+## license
+
+MIT

llm_api_scope-0.9.0/apiscope/add/__init__.py

@@ -0,0 +1 @@
+# apiscope/add/__init__.py

llm_api_scope-0.9.0/apiscope/add/app.py

@@ -0,0 +1,119 @@
+# apiscope/add/app.py
+
+from pathlib import Path
+from typing import cast
+
+import typer
+from pydantic import BaseModel, ValidationError
+
+from apiscope.add.constants import COMMAND_NAME, MESSAGE_TEMPLATES
+from apiscope.add.context import AddCommandContext
+from apiscope.add.preflight import run_preflight
+from apiscope.add.schema import AddOptions
+from apiscope.config import (
+    ConfigError,
+    ensure_config_file,
+    extract_config_sources,
+    save_config_file,
+    with_config_sources,
+)
+from apiscope.constants import CONFIG_SCHEMA_REF
+from apiscope.constants import MESSAGE_TEMPLATES as ROOT_MESSAGE_TEMPLATES
+from apiscope.context import RuntimeContext
+from apiscope.errors import MessageError
+from apiscope.output import Report, emit_report
+from apiscope.schema import SOURCE_SELECTOR_ALL, DocumentType, GlobalConfigFile, ProjectConfigFile, RuntimeSource
+
+_MESSAGE_TEMPLATES = {**ROOT_MESSAGE_TEMPLATES, **MESSAGE_TEMPLATES}
+
+app = typer.Typer(
+    name=COMMAND_NAME,
+    help=MESSAGE_TEMPLATES["add.help.command"],
+    subcommand_metavar="",
+    context_settings={"allow_interspersed_args": True},
+)
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help=MESSAGE_TEMPLATES["add.help.argument.name"]),
+    source: str = typer.Argument(..., help=MESSAGE_TEMPLATES["add.help.argument.source"]),
+    doc_type: str = typer.Option(..., "--type", help=MESSAGE_TEMPLATES["add.help.option.type"]),
+    ttl: int | None = typer.Option(None, "--ttl", help=MESSAGE_TEMPLATES["add.help.option.ttl"]),
+) -> None:
+    runtime_context = ctx.find_object(RuntimeContext)
+    if runtime_context is None:
+        raise MessageError("add.error.runtime_context_unavailable")
+
+    try:
+        if name == SOURCE_SELECTOR_ALL:
+            raise MessageError("add.error.reserved_name", {"name": name})
+        options = AddOptions(name=name, doc_type=cast(DocumentType, doc_type), doc_src=source, doc_ttl=ttl)
+        command_context = AddCommandContext(runtime=runtime_context, options=options)
+        run_preflight(command_context)
+        _add_source(command_context)
+    except ValidationError:
+        error = MessageError("add.error.invalid_options", {"name": name})
+        _emit_error(runtime_context, error)
+        raise typer.Exit(code=1) from error
+    except MessageError as error:
+        _emit_error(runtime_context, error)
+        raise typer.Exit(code=1) from error
+
+    emit_report(
+        Report(
+            status="ok",
+            scope=runtime_context.scope,
+            action=COMMAND_NAME,
+            meta={"name": options.name, "type": options.doc_type},
+        ),
+        output_format=runtime_context.options.output_format,
+    )
+
+
+def _add_source(command_context: AddCommandContext) -> None:
+    runtime = command_context.runtime
+    path, model = _config_target(runtime)
+    try:
+        config_file = ensure_config_file(path, model, schema_ref=CONFIG_SCHEMA_REF)
+    except ConfigError as error:
+        raise MessageError("add.error.persistence.read_failed", {"path": str(path)}) from error
+
+    sources = extract_config_sources(config_file)
+    if command_context.options.name in sources:
+        raise MessageError("add.error.duplicate_name", {"name": command_context.options.name})
+
+    source = RuntimeSource(
+        doc_type=command_context.options.doc_type,
+        doc_src=command_context.options.doc_src,
+        doc_ttl=command_context.options.doc_ttl,
+    )
+    sources[command_context.options.name] = source
+    updated_config = with_config_sources(config_file, sources)
+    try:
+        save_config_file(path, updated_config)
+    except ConfigError as error:
+        raise MessageError("add.error.persistence.write_failed", {"path": str(path)}) from error
+
+
+def _config_target(runtime: RuntimeContext) -> tuple[Path, type[BaseModel]]:
+    if runtime.options.global_only:
+        return runtime.paths.home.config, GlobalConfigFile
+    if runtime.paths.project is None:
+        raise MessageError("add.error.project_required")
+    return runtime.paths.project.config, ProjectConfigFile
+
+
+def _emit_error(runtime: RuntimeContext, error: MessageError) -> None:
+    emit_report(
+        Report(
+            status="error",
+            scope=runtime.scope,
+            action=COMMAND_NAME,
+            code=error.code,
+            meta=error.values,
+        ),
+        output_format=runtime.options.output_format,
+        message_templates=_MESSAGE_TEMPLATES,
+    )

llm_api_scope-0.9.0/apiscope/add/constants.py

@@ -0,0 +1,20 @@
+# apiscope/add/constants.py
+
+from typing import Final
+
+COMMAND_NAME: Final = "add"
+
+MESSAGE_TEMPLATES: Final[dict[str, str]] = {
+    "add.help.command": "add a source to the selected configuration",
+    "add.help.argument.name": "the source name",
+    "add.help.argument.source": "the source location",
+    "add.help.option.type": "the source document type",
+    "add.help.option.ttl": "the source cache TTL in days",
+    "add.error.runtime_context_unavailable": "runtime context is unavailable",
+    "add.error.invalid_options": ("source {name} has an invalid definition. check its type, location, and TTL"),
+    "add.error.project_required": "a Git project is required unless --global is used",
+    "add.error.duplicate_name": "source {name} already exists",
+    "add.error.reserved_name": "source name {name} is reserved",
+    "add.error.persistence.read_failed": "cannot read the configuration at {path}",
+    "add.error.persistence.write_failed": "cannot update the configuration at {path}",
+}

llm_api_scope-0.9.0/apiscope/add/context.py

@@ -0,0 +1,12 @@
+# apiscope/add/context.py
+
+from dataclasses import dataclass
+
+from apiscope.add.schema import AddOptions
+from apiscope.context import RuntimeContext
+
+
+@dataclass(frozen=True, slots=True)
+class AddCommandContext:
+    runtime: RuntimeContext
+    options: AddOptions

llm_api_scope-0.9.0/apiscope/add/preflight.py

@@ -0,0 +1,10 @@
+# apiscope/add/preflight.py
+
+from apiscope.add.context import AddCommandContext
+from apiscope.errors import MessageError
+
+
+def run_preflight(command_context: AddCommandContext) -> None:
+    runtime = command_context.runtime
+    if not runtime.options.global_only and runtime.paths.project is None:
+        raise MessageError("add.error.project_required")

llm_api_scope-0.9.0/apiscope/add/schema.py

@@ -0,0 +1,12 @@
+# apiscope/add/schema.py
+
+from pydantic import Field, PositiveInt
+
+from apiscope.schema import DocumentType, StrictSchemaModel
+
+
+class AddOptions(StrictSchemaModel):
+    name: str = Field(min_length=1)
+    doc_type: DocumentType
+    doc_src: str = Field(min_length=1)
+    doc_ttl: PositiveInt | None = None

llm_api_scope-0.9.0/apiscope/app.py

@@ -0,0 +1,89 @@
+# apiscope/app.py
+
+import typer
+
+from apiscope.add.app import app as add_app
+from apiscope.add.constants import COMMAND_NAME as ADD_COMMAND_NAME
+from apiscope.constants import MESSAGE_TEMPLATES
+from apiscope.context import RootOptions
+from apiscope.list.app import app as list_app
+from apiscope.list.constants import COMMAND_NAME as LIST_COMMAND_NAME
+from apiscope.output import OutputFormat, Report, emit_report
+from apiscope.preflight import PreflightError, run_preflight, run_read_preflight
+from apiscope.read.app import app as read_app
+from apiscope.read.constants import COMMAND_NAME as READ_COMMAND_NAME
+from apiscope.remove.app import app as remove_app
+from apiscope.remove.constants import COMMAND_NAME as REMOVE_COMMAND_NAME
+from apiscope.schema import ConfigScope
+from apiscope.skill.app import app as skill_app
+from apiscope.skill.constants import COMMAND_NAME as SKILL_COMMAND_NAME
+from apiscope.sync.app import app as sync_app
+from apiscope.sync.constants import COMMAND_NAME as SYNC_COMMAND_NAME
+from apiscope.view.app import app as view_app
+from apiscope.view.constants import COMMAND_NAME as VIEW_COMMAND_NAME
+
+# ==============================================================================
+# app
+# ==============================================================================
+
+
+app = typer.Typer(
+    rich_markup_mode=None,
+    pretty_exceptions_enable=False,
+    help=MESSAGE_TEMPLATES["root.help.app"],
+)
+
+app.add_typer(add_app, name=ADD_COMMAND_NAME)
+app.add_typer(remove_app, name=REMOVE_COMMAND_NAME)
+app.add_typer(read_app, name=READ_COMMAND_NAME)
+app.add_typer(list_app, name=LIST_COMMAND_NAME)
+app.add_typer(sync_app, name=SYNC_COMMAND_NAME)
+app.add_typer(view_app, name=VIEW_COMMAND_NAME)
+app.add_typer(skill_app, name=SKILL_COMMAND_NAME)
+
+# write commands prepare assets; read commands only load and project
+_WRITE_COMMANDS = {ADD_COMMAND_NAME, REMOVE_COMMAND_NAME, SYNC_COMMAND_NAME}
+
+# ==============================================================================
+# callback
+# ==============================================================================
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(
+    ctx: typer.Context,
+    global_only: bool = typer.Option(
+        False,
+        "--global",
+        "-g",
+        help=MESSAGE_TEMPLATES["root.help.option.global"],
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help=MESSAGE_TEMPLATES["root.help.option.json"],
+    ),
+) -> None:
+    output_format = OutputFormat.JSON if json_output else OutputFormat.TEXT
+    root_options = RootOptions(global_only=global_only, output_format=output_format)
+    try:
+        if ctx.invoked_subcommand in _WRITE_COMMANDS:
+            runtime_context = run_preflight(options=root_options)
+        else:
+            runtime_context = run_read_preflight(options=root_options)
+    except PreflightError as error:
+        emit_report(
+            Report(
+                status="error",
+                scope=ConfigScope.HOME if global_only else ConfigScope.PROJECT,
+                action="preflight",
+                code=error.code,
+                meta=error.values,
+            ),
+            output_format=output_format,
+            message_templates=MESSAGE_TEMPLATES,
+        )
+        raise typer.Exit(code=1) from error
+    ctx.obj = runtime_context
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())