llm-api-scope 0.5.0__tar.gz → 0.5.1__tar.gz

{llm_api_scope-0.5.0/llm_api_scope.egg-info → llm_api_scope-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-api-scope
-Version: 0.5.0
+Version: 0.5.1
 Summary: read and cache structured documents from remote for LLM agents
 Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
 License: MIT License
@@ -73,9 +73,14 @@ browse OpenAPI specifications with subcommands for discovering, listing, and des
 
 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.
 
+### rfc
+
+read, search, and navigate RFC documents from the IETF.
+
+the metadata index is mirrored once via rsync. individual text files are fetched on demand and cached locally. you can browse the table of contents, jump to a section (XML) or page (TXT), filter the index by status or source, and run keyword searches against fulltext content.
+
 ## future
 
-- read RFC documents by number
 - read academic papers from arxiv
 - more formal document formats as the need arises
 

{llm_api_scope-0.5.0 → llm_api_scope-0.5.1}/README.md

@@ -24,9 +24,14 @@ browse OpenAPI specifications with subcommands for discovering, listing, and des
 
 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.
 
+### rfc
+
+read, search, and navigate RFC documents from the IETF.
+
+the metadata index is mirrored once via rsync. individual text files are fetched on demand and cached locally. you can browse the table of contents, jump to a section (XML) or page (TXT), filter the index by status or source, and run keyword searches against fulltext content.
+
 ## future
 
-- read RFC documents by number
 - read academic papers from arxiv
 - more formal document formats as the need arises
 

{llm_api_scope-0.5.0 → llm_api_scope-0.5.1}/apiscope/config.py

@@ -1,6 +1,7 @@
 # apiscope/config.py
 
 import json
+import time
 from contextlib import contextmanager
 from os import environ
 from pathlib import Path
@@ -27,13 +28,36 @@ CACHE_ROOT = DEFAULT_ROOT / "cache"
 # ==============================================================================
 
 
-class OpenapiConfig(BaseModel):
+class BaseConfig(BaseModel):
+    cache_ttl: int  # seconds
+
+    def is_stale_since(self, timestamp: float) -> bool:
+        return time.time() - timestamp > self.cache_ttl
+
+    def is_stale_path(self, path: Path) -> bool:
+        if not path.exists():
+            return True
+        stat = path.stat()
+        latest = max(stat.st_mtime, stat.st_ctime)
+        return self.is_stale_since(latest)
+
+
+class OpenapiConfig(BaseConfig):
     proxy: str | None = Field(default=None)
     alias: dict[str, str] = Field(default_factory=dict)
 
+    # override
+    cache_ttl: int = Field(default=60 * 60 * 24)  # 1 day
+
+
+class RfcConfig(BaseConfig):
+    # override
+    cache_ttl: int = Field(default=60 * 60 * 24 * 7)  # 1 week
+
 
 class Config(BaseModel):
     openapi: OpenapiConfig = Field(default_factory=OpenapiConfig)
+    rfc: RfcConfig = Field(default_factory=RfcConfig)
 
     @classmethod
     def read(cls, path: Path) -> "Config":

{llm_api_scope-0.5.0 → llm_api_scope-0.5.1}/apiscope/openapi/app.py

@@ -7,7 +7,7 @@ from typing import Any
 import typer
 
 from apiscope.config import CACHE_ROOT, Config
-from apiscope.openapi.fetch import fetch_openapi_spec
+from apiscope.openapi.fetch import fetch_openapi_spec, openapi_cache_path
 from apiscope.openapi.reader import HttpMethod, OpenapiReader
 from apiscope.openapi.schema import OpenapiCommandContext
 from apiscope.openapi.spec import spec_app
@@ -26,16 +26,20 @@ def _resolve_source(alias_or_source: str, config: Config) -> str:
     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)
+def _load_reader(
+    source: str, cache_dir: Path, proxy: str | None = None, refresh: bool = False
+) -> OpenapiReader:
+    cached = fetch_openapi_spec(source, cache_dir, proxy, refresh=refresh)
     return OpenapiReader.load(cached)
 
 
-def _get_reader(source: str, ctx: typer.Context) -> OpenapiReader:
+def _get_reader(source: str, ctx: typer.Context, force: bool = False) -> 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)
+    cache_path = openapi_cache_path(resolved, cache_dir)
+    stale = ctx.obj.config.openapi.is_stale_path(cache_path)
+    return _load_reader(resolved, cache_dir, proxy, refresh=force or stale)
 
 
 # ==============================================================================
@@ -61,9 +65,9 @@ def list_operations(
     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"),
+    force: bool = typer.Option(False, "--force", help="force re-fetch ignoring cache"),
 ) -> None:
-    # load and resolve the spec
-    reader = _get_reader(source, ctx)
+    reader = _get_reader(source, ctx, force=force)
 
     # collect all operations (path + method + identity fields)
     operations: list[dict[str, Any]] = []
@@ -106,9 +110,9 @@ def describe_operation(
     request: bool = typer.Option(
         default=False, show_default=False, help="show only request fields, omit responses"
     ),
+    force: bool = typer.Option(False, "--force", help="force re-fetch ignoring cache"),
 ) -> None:
-    # load and resolve the spec
-    reader = _get_reader(source, ctx)
+    reader = _get_reader(source, ctx, force=force)
 
     # merge path-item parameters with operation parameters
     path_item = reader.paths.get(path, {})
@@ -132,8 +136,9 @@ def describe_operation(
 def show_info(
     ctx: typer.Context,
     source: str = typer.Argument(help="alias or path to the OpenAPI spec"),
+    force: bool = typer.Option(False, "--force", help="force re-fetch ignoring cache"),
 ) -> None:
-    reader = _get_reader(source, ctx)
+    reader = _get_reader(source, ctx, force=force)
 
     META_KEYS = ("openapi", "info", "servers", "tags", "security", "externalDocs")
     meta = {k: v for k, v in reader.raw.items() if k in META_KEYS}

llm_api_scope-0.5.1/apiscope/openapi/fetch.py

@@ -0,0 +1,58 @@
+# 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 openapi_cache_path(source: str, cache_dir: Path) -> Path:
+    if "://" in source:
+        path = unquote(urlparse(source).path).rstrip()
+    else:
+        path = source
+    suffix = Path(path).suffix.lower()
+    ext = suffix if suffix in OPENAPI_EXTENSIONS else ".json"
+    return cache_dir / f"{_cache_key(source)}{ext}"
+
+
+def _fetch_local(source: str, cache_dir: Path, refresh: bool = False) -> Path:
+    cache_path = openapi_cache_path(source, cache_dir)
+
+    if refresh or 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, refresh: bool = False
+) -> Path:
+    cache_path = openapi_cache_path(url, cache_dir)
+
+    if refresh or 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, refresh: bool = False
+) -> Path:
+    if "://" in source:
+        return _fetch_remote(source, cache_dir, proxy, refresh=refresh)
+    return _fetch_local(source, cache_dir, refresh=refresh)

{llm_api_scope-0.5.0 → llm_api_scope-0.5.1}/apiscope/rfc/app.py

@@ -88,10 +88,20 @@ def _show_page_info(content: str, number: int, rfc_ctx: RfcCommandContext) -> No
 
 
 @app.command(name="sync", help="download RFC metadata index via rsync")
-def sync_index(ctx: typer.Context) -> None:
+def sync_index(
+    ctx: typer.Context,
+    force: bool = typer.Option(False, "--force", help="force re-sync ignoring cache TTL"),
+) -> None:
     rfc_ctx = ctx.obj.rfc_command_context
+    rfc_config = ctx.obj.config.rfc
+    index_dir = rfc_ctx.index_json_dir
+
+    if not force and not rfc_config.is_stale_path(index_dir):
+        typer.echo("index is up to date")
+        return
+
     typer.echo("syncing via rsync...")
-    err = fetch_all_index_json(rfc_ctx.index_json_dir)
+    err = fetch_all_index_json(index_dir)
     if err is not None:
         typer.echo(f"sync failed\n{err}", err=True)
         raise typer.Exit(code=1)
@@ -139,8 +149,10 @@ def read_content(
     section: str | None = typer.Option(None, "--section", help="extract by section id (XML only)"),
     page: int | None = typer.Option(None, "--page", help="extract by page number (TXT only)"),
     json_output: bool = typer.Option(False, "--json", help="output as JSON"),
+    force: bool = typer.Option(False, "--force", help="force re-fetch ignoring cache TTL"),
 ) -> None:
     rfc_ctx = ctx.obj.rfc_command_context
+    rfc_config = ctx.obj.config.rfc
     meta = rfc_ctx.get_index_json(number)
     if meta is None:
         typer.echo(f"rfc {number} not found", err=True)
@@ -158,7 +170,7 @@ def read_content(
         raise typer.Exit(code=1)
 
     # ensure content is available locally
-    if not content_path.exists():
+    if force or rfc_config.is_stale_path(content_path):
         typer.echo(f"fetching <{content_path.name}> via rsync...")
         err = fetch_content_by_number(number, content_path.parent, fmt)
         if err is not None:
@@ -235,8 +247,10 @@ def search_rfc(
     no_snippet: bool = typer.Option(False, "--no-snippet", help="hide content snippet"),
     limit: int = typer.Option(20, "--limit", help="max results shown"),
     offset: int = typer.Option(0, "--offset", help="skip first N results"),
+    force: bool = typer.Option(False, "--force", help="force re-fetch ignoring cache TTL"),
 ) -> None:
     rfc_ctx = ctx.obj.rfc_command_context
+    rfc_config = ctx.obj.config.rfc
     # step 1: dispatch mode
     index_filters = [status, since, until, author, title, abstract, keywords_field, source]
     fulltext_mode = number is not None and term is not None
@@ -272,7 +286,7 @@ def search_rfc(
             raise typer.Exit(code=1)
 
         content_path = rfc_ctx.get_content_txt_path(number)
-        if not content_path.exists():
+        if force or rfc_config.is_stale_path(content_path):
             typer.echo(f"fetching <{content_path.name}> via rsync...")
             err = fetch_content_by_number(number, content_path.parent, "txt")
             if err is not None:

{llm_api_scope-0.5.0 → llm_api_scope-0.5.1/llm_api_scope.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-api-scope
-Version: 0.5.0
+Version: 0.5.1
 Summary: read and cache structured documents from remote for LLM agents
 Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
 License: MIT License
@@ -73,9 +73,14 @@ browse OpenAPI specifications with subcommands for discovering, listing, and des
 
 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.
 
+### rfc
+
+read, search, and navigate RFC documents from the IETF.
+
+the metadata index is mirrored once via rsync. individual text files are fetched on demand and cached locally. you can browse the table of contents, jump to a section (XML) or page (TXT), filter the index by status or source, and run keyword searches against fulltext content.
+
 ## future
 
-- read RFC documents by number
 - read academic papers from arxiv
 - more formal document formats as the need arises
 

{llm_api_scope-0.5.0 → llm_api_scope-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "llm-api-scope"
-version = "0.5.0"
+version = "0.5.1"
 description = "read and cache structured documents from remote for LLM agents"
 readme = "README.md"
 license = { file = "LICENSE" }

llm_api_scope-0.5.0/apiscope/openapi/fetch.py

@@ -1,49 +0,0 @@
-# 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)