llm-api-scope 0.3.0__tar.gz → 0.4.0__tar.gz

llm_api_scope-0.4.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: llm-api-scope
+Version: 0.4.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 fetches specifications from local files or remote URLs, caches them, and outputs structured JSON that agents can consume directly. no html parsing, no keyword ranking — just faithful extraction from the source document.
+
+## commands
+
+run `apiscope --help` to see all available commands.
+
+### openapi
+
+browse OpenAPI specifications with subcommands for discovering, listing, and describing operations.
+
+aliases let you register frequently used specs once and reference them by short name. fetching is transparent — local copies are cached for fast repeat access, and a proxy can be configured for restricted networks.
+
+## future
+
+- read RFC documents by number
+- read academic papers from arxiv
+- more formal document formats as the need arises
+
+## license
+
+MIT

llm_api_scope-0.4.0/README.md

@@ -0,0 +1,35 @@
+# 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 fetches specifications from local files or remote URLs, caches them, and outputs structured JSON that agents can consume directly. no html parsing, no keyword ranking — just faithful extraction from the source document.
+
+## commands
+
+run `apiscope --help` to see all available commands.
+
+### openapi
+
+browse OpenAPI specifications with subcommands for discovering, listing, and describing operations.
+
+aliases let you register frequently used specs once and reference them by short name. fetching is transparent — local copies are cached for fast repeat access, and a proxy can be configured for restricted networks.
+
+## future
+
+- read RFC documents by number
+- read academic papers from arxiv
+- more formal document formats as the need arises
+
+## license
+
+MIT

llm_api_scope-0.4.0/apiscope/config.py

@@ -0,0 +1,117 @@
+# apiscope/config.py
+
+import json
+from contextlib import contextmanager
+from os import environ
+from pathlib import Path
+from typing import Generator
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+
+# load .env file at module load time
+load_dotenv()
+
+# brand identity
+# ==============
+APP_NAME = "apiscope"
+DEFAULT_HOME = Path(environ.get("APISCOPE_HOME", str(Path.home())))
+DEFAULT_ROOT = DEFAULT_HOME / ".apiscope"
+DEFAULT_CONFIG_PATH = DEFAULT_ROOT / "config.json"
+DEFAULT_CONFIG_SCHEMA_PATH = DEFAULT_ROOT / "config.schema.json"
+
+CACHE_ROOT = DEFAULT_ROOT / "cache"
+
+# ==============================================================================
+# config model
+# ==============================================================================
+
+
+class OpenapiConfig(BaseModel):
+    proxy: str | None = Field(default=None)
+    alias: dict[str, str] = Field(default_factory=dict)
+
+
+class Config(BaseModel):
+    openapi: OpenapiConfig = Field(default_factory=OpenapiConfig)
+
+    @classmethod
+    def read(cls, path: Path) -> "Config":
+        if not path.exists():
+            raise FileNotFoundError(f"[{path}] not found.")
+        return cls.model_validate_json(path.read_text())
+
+    @classmethod
+    @contextmanager
+    def edit(cls, path: Path) -> Generator["Config", None, None]:
+        if not path.exists():
+            raise FileNotFoundError(f"[{path}] not found.")
+        config = cls.model_validate_json(path.read_text())
+        yield config
+        if isinstance(config, Config):
+            config.write(path)
+
+    def write(self, path: Path) -> None:
+        data = {"$schema": DEFAULT_CONFIG_SCHEMA_PATH.as_uri()} | self.model_dump()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2) + "\n")
+
+    def merge(self, other: "Config") -> "Config":
+        merged = self.model_copy(deep=True)
+        merged.openapi.alias |= other.openapi.alias
+        if other.openapi.proxy is not None:
+            merged.openapi.proxy = other.openapi.proxy
+        return merged
+
+
+# ==============================================================================
+# helpers
+# ==============================================================================
+
+
+def _get_project_root() -> Path | None:
+    workpath = Path.cwd()
+    while True:
+        if (workpath / ".git").exists():
+            return workpath
+        parent = workpath.parent
+        if parent == workpath:
+            return None
+        workpath = parent
+
+
+# ==============================================================================
+# public API
+# ==============================================================================
+
+
+DEFAULT_CONFIG = Config()
+
+
+def get_project_config_path() -> Path | None:
+    project_root = _get_project_root()
+    if project_root is None:
+        return None
+    return project_root / f".{APP_NAME}.config.json"
+
+
+def get_config() -> Config:
+    # ensure the default config exists
+    if not DEFAULT_CONFIG_PATH.exists():
+        DEFAULT_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        DEFAULT_CONFIG.write(DEFAULT_CONFIG_PATH)
+
+    # ensure the default config schema exists
+    DEFAULT_CONFIG_SCHEMA_PATH.parent.mkdir(parents=True, exist_ok=True)
+    DEFAULT_CONFIG_SCHEMA_PATH.write_text(json.dumps(Config.model_json_schema(), indent=2))
+
+    # load the global config
+    global_config = Config.model_validate_json(DEFAULT_CONFIG_PATH.read_text())
+
+    # load and merge the project config
+    project_config_path = get_project_config_path()
+    if project_config_path is not None and project_config_path.exists():
+        project_config = Config.model_validate_json(project_config_path.read_text())
+        return global_config.merge(project_config)
+
+    return global_config

llm_api_scope-0.4.0/apiscope/main.py

@@ -0,0 +1,68 @@
+# apiscope/main.py
+#
+# structure convention:
+#
+#   subcommands live under apiscope/<group>/ as subdirectory packages.
+#   each subdirectory contains:
+#
+#     app.py    — command definitions (typer.Typer app)
+#     schema.py — context object for this command group (read-only contract)
+#
+#   parent callbacks inject ctx.obj with CommandContext(config=...).
+#   subcommand callbacks extend ctx.obj.extras with group-specific keys.
+#   schema.py exists solely to document the context shape — no runtime logic.
+
+import typer
+
+from apiscope.config import APP_NAME, DEFAULT_ROOT, get_config
+from apiscope.openapi import openapi_app
+from apiscope.schema import CommandContext
+
+# ==============================================================================
+# app
+# ==============================================================================
+
+app = typer.Typer(
+    rich_markup_mode=None,
+    pretty_exceptions_enable=False,
+    help="a reader for network resources",
+)
+
+# ==============================================================================
+# callback
+# ==============================================================================
+
+
+@app.callback(invoke_without_command=True)
+def callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        return
+    ctx.obj = CommandContext(config=get_config())
+
+
+# ==============================================================================
+# subcommands
+# ==============================================================================
+
+app.add_typer(openapi_app, name="openapi")
+
+# ==============================================================================
+# commands
+# ==============================================================================
+
+
+@app.command(help="check that apiscope is installed and working")
+def health(ctx: typer.Context) -> None:
+    cache_dir = DEFAULT_ROOT / "cache"
+    DEFAULT_ROOT.mkdir(parents=True, exist_ok=True)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    typer.echo(f"{APP_NAME} is healthy")
+
+
+# ==============================================================================
+# entry point
+# ==============================================================================
+
+if __name__ == "__main__":
+    app()

llm_api_scope-0.4.0/apiscope/openapi/__init__.py

@@ -0,0 +1,5 @@
+# apiscope/openapi/__init__.py
+
+from apiscope.openapi.app import app as openapi_app
+
+__all__ = ["openapi_app"]

llm_api_scope-0.4.0/apiscope/openapi/app.py

@@ -0,0 +1,147 @@
+# apiscope/openapi/app.py
+
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from apiscope.config import CACHE_ROOT, Config
+from apiscope.openapi.fetch import fetch_openapi_spec
+from apiscope.openapi.reader import HttpMethod, OpenapiReader
+from apiscope.openapi.schema import OpenapiCommandContext
+from apiscope.openapi.spec import spec_app
+
+app = typer.Typer(help="browse OpenAPI specifications")
+
+
+# ==============================================================================
+# helpers
+# ==============================================================================
+
+
+def _resolve_source(alias_or_source: str, config: Config) -> str:
+    if alias_or_source in config.openapi.alias:
+        return config.openapi.alias[alias_or_source]
+    return alias_or_source
+
+
+def _load_reader(source: str, cache_dir: Path, proxy: str | None = None) -> OpenapiReader:
+    cached = fetch_openapi_spec(source, cache_dir, proxy)
+    return OpenapiReader.load(cached)
+
+
+def _get_reader(source: str, ctx: typer.Context) -> OpenapiReader:
+    resolved = _resolve_source(source, ctx.obj.config)
+    cache_dir = ctx.obj.openapi_command_context.cache_dir
+    proxy = ctx.obj.config.openapi.proxy
+    return _load_reader(resolved, cache_dir, proxy)
+
+
+# ==============================================================================
+# callback
+# ==============================================================================
+
+
+@app.callback()
+def openapi_callback(ctx: typer.Context) -> None:
+    cache_dir = CACHE_ROOT / "openapi"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    ctx.obj.openapi_command_context = OpenapiCommandContext(cache_dir=cache_dir)
+
+
+# ==============================================================================
+# operation commands
+# ==============================================================================
+
+
+@app.command(name="list", help="list operations from an OpenAPI spec")
+def list_operations(
+    ctx: typer.Context,
+    source: str = typer.Argument(help="alias or path to the OpenAPI spec"),
+    tag: str | None = typer.Option(default=None, help="filter by tag"),
+    method: str | None = typer.Option(default=None, help="filter by HTTP method"),
+) -> None:
+    # load and resolve the spec
+    reader = _get_reader(source, ctx)
+
+    # collect all operations (path + method + identity fields)
+    operations: list[dict[str, Any]] = []
+    methods = set(m.value for m in HttpMethod)
+    for path_name, path_item in reader.paths.items():
+        for mthd in path_item:
+            if mthd not in methods:
+                continue
+            # summary comes from the operation, not the path-item
+            op = path_item[mthd]
+            summary = op.get("summary", "")
+            operation_id = op.get("operationId", "")
+            tags = op.get("tags", [])
+
+            # apply filters
+            if tag is not None and tag not in tags:
+                continue
+            if method is not None and mthd != method:
+                continue
+
+            operations.append(
+                {
+                    "path": path_name,
+                    "method": mthd,
+                    "summary": summary,
+                    "operationId": operation_id,
+                    "tags": tags,
+                }
+            )
+
+    typer.echo(json.dumps(operations, ensure_ascii=False))
+
+
+@app.command(name="describe", help="describe a single operation")
+def describe_operation(
+    ctx: typer.Context,
+    source: str = typer.Argument(help="alias or path to the OpenAPI spec"),
+    path: str = typer.Argument(help="operation path"),
+    method: str = typer.Argument(help="HTTP method"),
+    request: bool = typer.Option(
+        default=False, show_default=False, help="show only request fields, omit responses"
+    ),
+) -> None:
+    # load and resolve the spec
+    reader = _get_reader(source, ctx)
+
+    # merge path-item parameters with operation parameters
+    path_item = reader.paths.get(path, {})
+    path_params = path_item.get("parameters", [])
+    op = reader.get_operation(path, HttpMethod(method))
+    op_params = op.get("parameters", [])
+
+    # build resolved operation dict
+    merged = {**op, "parameters": path_params + op_params}
+    resolved = reader.resolve_ref(merged)
+
+    # strip response fields when --request is set
+    if request:
+        resolved.pop("responses", None)
+        # also drop any $ref key that resolved to a response-like structure
+
+    typer.echo(json.dumps(resolved, ensure_ascii=False))
+
+
+@app.command(name="info", help="show OpenAPI spec metadata")
+def show_info(
+    ctx: typer.Context,
+    source: str = typer.Argument(help="alias or path to the OpenAPI spec"),
+) -> None:
+    reader = _get_reader(source, ctx)
+
+    META_KEYS = ("openapi", "info", "servers", "tags", "security", "externalDocs")
+    meta = {k: v for k, v in reader.raw.items() if k in META_KEYS}
+    typer.echo(json.dumps(meta, ensure_ascii=False))
+
+
+# ==============================================================================
+# subcommands
+# ==============================================================================
+
+app.add_typer(spec_app, name="spec")

llm_api_scope-0.4.0/apiscope/openapi/fetch.py

@@ -0,0 +1,49 @@
+# apiscope/openapi/fetch.py
+
+import shutil
+from hashlib import sha256
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+import httpx
+
+OPENAPI_EXTENSIONS = {".json", ".yaml", ".yml"}
+
+
+def _cache_key(source: str) -> str:
+    return sha256(source.encode()).hexdigest()
+
+
+def _fetch_local(source: str, cache_dir: Path) -> Path:
+    suffix = Path(source).suffix.lower()
+    ext = suffix if suffix in OPENAPI_EXTENSIONS else ".json"
+    cache_path = cache_dir / f"{_cache_key(source)}{ext}"
+
+    if not cache_path.exists():
+        src = Path(source).expanduser().resolve()
+        shutil.copy2(src, cache_path)
+
+    return cache_path
+
+
+def _fetch_remote(url: str, cache_dir: Path, proxy: str | None = None) -> Path:
+    path = unquote(urlparse(url).path).rstrip()
+    suffix = Path(path).suffix.lower()
+    ext = suffix if suffix in OPENAPI_EXTENSIONS else ".json"
+    cache_path = cache_dir / f"{_cache_key(url)}{ext}"
+
+    if not cache_path.exists():
+        client_kwargs: dict = {}
+        if proxy is not None:
+            client_kwargs["proxy"] = proxy
+        resp = httpx.get(url, follow_redirects=True, **client_kwargs)
+        resp.raise_for_status()
+        cache_path.write_bytes(resp.content)
+
+    return cache_path
+
+
+def fetch_openapi_spec(source: str, cache_dir: Path, proxy: str | None = None) -> Path:
+    if "://" in source:
+        return _fetch_remote(source, cache_dir, proxy)
+    return _fetch_local(source, cache_dir)

llm_api_scope-0.4.0/apiscope/openapi/reader.py

@@ -0,0 +1,85 @@
+# apiscope/openapi/reader.py
+
+import json
+from enum import StrEnum
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+
+class HttpMethod(StrEnum):
+    GET = "get"
+    PUT = "put"
+    POST = "post"
+    DELETE = "delete"
+    OPTIONS = "options"
+    HEAD = "head"
+    PATCH = "patch"
+    TRACE = "trace"
+
+
+class OpenapiReader:
+    _payload: dict[str, Any]
+
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._payload = payload
+
+    @classmethod
+    def load(cls, path: Path) -> "OpenapiReader":
+        text = path.read_text(encoding="utf-8")
+        if path.suffix in (".yaml", ".yml"):
+            payload = yaml.safe_load(text)
+        else:
+            payload = json.loads(text)
+        return cls(payload)
+
+    @property
+    def paths(self) -> dict[str, dict[str, Any]]:
+        return cast(dict[str, dict[str, Any]], self._payload.get("paths", {}))
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        return self._payload
+
+    def filter_paths(self, *methods: HttpMethod) -> dict[str, dict[str, Any]]:
+        method_set = set(methods)
+        result: dict[str, dict[str, Any]] = {}
+        for path_name, path_item in self.paths.items():
+            filtered: dict[str, Any] = {k: v for k, v in path_item.items() if k in method_set}
+            if filtered:
+                result[path_name] = filtered
+        return result
+
+    def get_operation(self, path: str, method: HttpMethod) -> dict[str, Any]:
+        path_item: dict[str, Any] = self._payload.get("paths", {}).get(path, {})
+        return cast(dict[str, Any], path_item.get(method, {}))
+
+    def resolve_ref(self, data: dict[str, Any]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for k, v in data.items():
+            if k == "$ref" and isinstance(v, str):
+                resolved = self._deref(v)
+                if resolved is not None:
+                    return self.resolve_ref(resolved)
+                result[k] = v
+            elif isinstance(v, dict):
+                result[k] = self.resolve_ref(v)
+            elif isinstance(v, list):
+                result[k] = [
+                    self.resolve_ref(item) if isinstance(item, dict) else item for item in v
+                ]
+            else:
+                result[k] = v
+        return result
+
+    def _deref(self, ref: str) -> dict[str, Any] | None:
+        if not ref.startswith("#/"):
+            return None
+        parts = ref.removeprefix("#/").split("/")
+        target: Any = self._payload
+        for part in parts:
+            if not isinstance(target, dict) or part not in target:
+                return None
+            target = target[part]
+        return target if isinstance(target, dict) else None

llm_api_scope-0.4.0/apiscope/openapi/schema.py

@@ -0,0 +1,15 @@
+# apiscope/openapi/schema.py
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from apiscope.openapi.spec.schema import SpecCommandContext
+
+
+class OpenapiCommandContext(BaseModel):
+    # openapi settings
+    cache_dir: Path
+
+    # sub command contexts
+    spec_command_context: SpecCommandContext | None = None

llm_api_scope-0.4.0/apiscope/openapi/spec/__init__.py

@@ -0,0 +1,5 @@
+# apiscope/openapi/spec/__init__.py
+
+from apiscope.openapi.spec.app import app as spec_app
+
+__all__ = ["spec_app"]