llm-api-scope 0.6.1__tar.gz → 0.8.0__tar.gz

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-api-scope
-Version: 0.6.1
+Version: 0.8.0
 Summary: read and cache structured documents from remote for LLM agents
 Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
 License: MIT License
@@ -79,6 +79,17 @@ 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.
 
+### skill
+
+output a combined command reference and strategy guide for AI agents.
+
+run `apiscope skill` to get a single document that covers every subcommand and
+how they fit together. the strategy guide classifies commands into management and
+usage groups, lists prerequisites in ABNF (RFC 5234), and provides workflow
+patterns with requirement levels (RFC 2119).
+
+agents read this output once at onboarding instead of running `--help` repeatedly.
+
 ### repo
 
 sync documentation directories from any git repository to a local cache.

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/README.md

@@ -30,6 +30,17 @@ 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.
 
+### skill
+
+output a combined command reference and strategy guide for AI agents.
+
+run `apiscope skill` to get a single document that covers every subcommand and
+how they fit together. the strategy guide classifies commands into management and
+usage groups, lists prerequisites in ABNF (RFC 5234), and provides workflow
+patterns with requirement levels (RFC 2119).
+
+agents read this output once at onboarding instead of running `--help` repeatedly.
+
 ### repo
 
 sync documentation directories from any git repository to a local cache.

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/apiscope/main.py

@@ -28,6 +28,7 @@ from apiscope.openapi import openapi_app
 from apiscope.repo import check_repo_deps, repo_app
 from apiscope.rfc import check_rfc_deps, rfc_app
 from apiscope.schema import CommandContext
+from apiscope.skill import skill_app
 
 # ==============================================================================
 # app
@@ -59,6 +60,7 @@ def callback(ctx: typer.Context) -> None:
 app.add_typer(openapi_app, name="openapi")
 app.add_typer(rfc_app, name="rfc")
 app.add_typer(repo_app, name="repo")
+app.add_typer(skill_app, name="skill")
 
 # ==============================================================================
 # commands

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/apiscope/openapi/app.py

@@ -65,6 +65,8 @@ 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"),
+    limit: int = typer.Option(default=20, help="max results shown"),
+    offset: int = typer.Option(default=0, help="skip first N results"),
     force: bool = typer.Option(False, "--force", help="force re-fetch ignoring cache"),
 ) -> None:
     reader = _get_reader(source, ctx, force=force)
@@ -98,7 +100,14 @@ def list_operations(
                 }
             )
 
-    typer.echo(json.dumps(operations, ensure_ascii=False))
+    total = len(operations)
+    operations = operations[offset : offset + limit]
+    typer.echo(
+        json.dumps(
+            {"total": total, "offset": offset, "limit": limit, "items": operations},
+            ensure_ascii=False,
+        )
+    )
 
 
 @app.command(name="describe", help="describe a single operation")

llm_api_scope-0.8.0/apiscope/skill/__init__.py

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

llm_api_scope-0.8.0/apiscope/skill/_usage.py

@@ -0,0 +1,75 @@
+# apiscope/skill/_usage.py
+#
+# synced with [docs/usage.txt] -> update both when a command changes.
+
+USAGE_TEXT = """\
+- apiscope # a reader for network resources
+  - health # check that apiscope is installed and working
+  - openapi # browse OpenAPI specifications
+    - info # show OpenAPI spec metadata
+      + [SOURCE] # alias or path to the OpenAPI spec
+      + [--force]? # force re-fetch ignoring cache
+    - list # list operations from an OpenAPI spec
+      + [SOURCE] # alias or path to the OpenAPI spec
+      + [--tag]? # filter by tag
+      + [--method]? # filter by HTTP method
+      + [--limit]? # max results shown
+      + [--offset]? # skip first N results
+      + [--force]? # force re-fetch ignoring cache
+    - describe # describe a single operation
+      + [SOURCE] # alias or path to the OpenAPI spec
+      + [PATH] # operation path
+      + [METHOD] # HTTP method
+      + [--request]? # show only request fields, omit responses
+      + [--force]? # force re-fetch ignoring cache
+    - spec # manage OpenAPI spec aliases
+      + [-g]? # edit global config instead of project config
+      - add # register a new alias for an OpenAPI spec
+        + [ALIAS] # alias name
+        + [SOURCE] # path or URL to the OpenAPI spec
+      - remove # remove a registered alias
+        + [ALIAS] # alias name
+      - list # list all registered aliases
+  - rfc # browse IETF RFC documents
+    - sync # download RFC metadata index via rsync
+      + [--force]? # force re-sync ignoring cache TTL
+    - info # show RFC metadata
+      + [NUMBER] # RFC number
+      + [--json]? # output as JSON
+    - read # show RFC content or table of contents
+      + [NUMBER] # RFC number
+      + [--section]? # extract by section id (XML only)
+      + [--page]? # extract by page number (TXT only)
+      + [--json]? # output as JSON
+      + [--force]? # force re-fetch ignoring cache TTL
+    - search # search RFC index or fulltext
+      + [NUMBER]? # RFC number (fulltext mode)
+      + [TERM]? # search term (fulltext mode)
+      + [--force]? # force re-fetch ignoring cache TTL (fulltext mode)
+      + [--status]...? # filter by status: ps, ds, std, bcp, info, exp, hist (index mode)
+      + [--since]? # filter by start year (index mode)
+      + [--until]? # filter by end year (index mode)
+      + [--author]? # filter by author name (index mode)
+      + [--title]? # filter by title keyword (index mode)
+      + [--abstract]? # filter by abstract keyword (index mode)
+      + [--keywords]? # filter by keywords field (index mode)
+      + [--source]? # filter by source / working group (index mode)
+      + [--context]? # lines of context around match (fulltext mode)
+      + [--no-snippet]? # hide content snippet (fulltext mode)
+      + [--limit]? # max results shown
+      + [--offset]? # skip first N results
+  - repo # sync documentation from git repositories
+    + [-g]? # edit global config instead of project config
+    - add # register a repo for syncing
+      + [URL] # git clone URL
+      + [DIR] # directory within repo to extract
+      + [--target]? # ref target (branch:, tag:, commit:)
+    - remove # remove a registered repo
+      + [URL] # git clone URL
+    - list # list registered repos
+    - sync # sync all registered repos to cache
+      + [--force]? # force re-sync ignoring cache TTL
+  - skill # output usage guide for ai agents
+    - install # install SKILL.md for code agent
+      + [TARGET]? # install directory (default: ~/.agents/skills)
+"""

llm_api_scope-0.8.0/apiscope/skill/app.py

@@ -0,0 +1,50 @@
+# apiscope/skill/app.py
+
+from pathlib import Path
+
+import typer
+
+from apiscope.skill._usage import USAGE_TEXT
+from apiscope.skill.docs import INSTALL_MD, STRATEGY_GUIDE
+
+app = typer.Typer(help="output usage guide for ai agents")
+
+
+# ==============================================================================
+# callback
+# ==============================================================================
+
+
+@app.callback(invoke_without_command=True)
+def skill_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+
+    typer.echo("=== COMMAND REFERENCE ===")
+    typer.echo()
+    typer.echo(USAGE_TEXT)
+    typer.echo()
+    typer.echo("=== STRATEGY GUIDE ===")
+    typer.echo()
+    typer.echo(STRATEGY_GUIDE)
+
+
+# ==============================================================================
+# commands
+# ==============================================================================
+
+
+@app.command(name="install", help="install SKILL.md for code agent")
+def install(
+    target: str | None = typer.Argument(None, help="install directory (default: ~/.agents/skills)"),
+) -> None:
+    if target is None:
+        target = str(Path.home() / ".agents" / "skills")
+
+    target_path = Path(target).expanduser().resolve()
+    skill_path = target_path / "apiscope" / "SKILL.md"
+
+    skill_path.parent.mkdir(parents=True, exist_ok=True)
+    skill_path.write_text(INSTALL_MD)
+
+    typer.echo(f"installed: {skill_path}")

llm_api_scope-0.8.0/apiscope/skill/docs.py

@@ -0,0 +1,141 @@
+# apiscope/skill/docs.py
+
+STRATEGY_GUIDE = """\
+PREMISE
+
+  apiscope is a content acquisition layer, not a consumption layer.
+  it fetches high-quality reference materials to local cache, then
+  you use your preferred tools (ripgrep, grep, less) to consume them.
+
+  - openapi: structured api specifications with built-in analysis helpers
+  - rfc: internet standards and best current practice documents
+  - repo: git repository documentation for offline access
+
+CLASSIFICATION
+
+  management commands (run once, configure the tool)
+
+    - apiscope health
+    - apiscope openapi spec add / remove / list
+    - apiscope repo add / remove / list / sync
+    - apiscope rfc sync
+
+  usage commands (run repeatedly, query content)
+
+    - apiscope openapi info / list / describe
+    - apiscope rfc info / read / search
+
+PREREQUISITES
+
+  the grammar notation used in this section follows <RFC 5234> ABNF.
+  the key words "MUST", "SHOULD", and "MAY" are to be interpreted
+  as described in <RFC 2119>.
+
+  openapi-query
+    =  spec-add *(info / list / describe)
+    ; spec-add MUST precede any query command
+
+  rfc-local
+    =  sync read
+    ; sync SHOULD precede read for local access
+
+  rfc-local-info
+    =  sync info
+    ; sync SHOULD precede info for metadata lookup
+
+  repo-consume
+    =  add sync grep
+    ; add then sync MUST precede local consumption
+
+WORKFLOWS
+
+  explore-api
+    =  spec-add info list describe
+    ; 1. register the spec
+    ; 2. check metadata
+    ; 3. browse operations
+    ; 4. examine a specific operation
+
+  read-rfc
+    =  sync *search read
+    ; 1. sync index
+    ; 2. optionally search for relevant RFCs
+    ; 3. read the selected RFC
+
+  integrate-repo
+    =  add sync grep
+    ; 1. register the repository
+    ; 2. sync all repos
+    ; 3. use ripgrep or grep on local cache
+
+TIPS
+
+  cache strategy
+
+    each domain has a different cache ttl reflecting content
+    stability. the [--force] flag MUST only be used when you
+    expect the remote content has changed since last fetch.
+
+    - openapi: 1 day
+    - rfc: 30 days
+    - repo: 7 days
+
+  config hierarchy
+
+    global config (<~/.apiscope/config.json>) holds personal
+    defaults. project config (<.apiscope.config.json>) holds
+    team-specific entries. project values override global ones
+    where overlap is defined.
+
+    [openapi spec add] without [-g] writes to project config.
+    teammates who clone the project get the same aliases.
+
+  openapi alias naming
+
+    aliases are shortcuts for spec URLs. use a naming convention
+    that makes the source obvious without checking [spec list].
+
+    - github-api, petstore-v3, stripe-v1
+
+  acquisition before analysis
+
+    rfc and repo pull documents to local cache. do not treat
+    apiscope search as a replacement for grep or ripgrep. the
+    intended workflow is: acquire local copy, then analyze with
+    your preferred tools.
+
+    openapi is the exception. it provides [list] for breadth,
+    [describe] for depth, and [info] for metadata. use [list]
+    first to scan endpoints, then [describe] to extract a
+    specific operation in detail.
+"""
+
+
+INSTALL_MD = """\
+---
+name: apiscope
+description: >-
+  Query OpenAPI specs, IETF RFCs, and synced git repo docs.
+  Use when searching API references, RFC standards,
+  or documentation of registered repos.
+---
+
+`apiscope` reads network resources to local cache.
+it covers openapi specs, ietf rfc documents, and git repo docs.
+
+discover commands with `--help`.
+  `apiscope --help`
+  `apiscope <sub> --help`
+
+read the full strategy guide.
+  `apiscope skill`
+
+find cached repo paths.
+  `apiscope repo list`
+
+search cached docs.
+  `rg <term> <cache-path>`
+
+prefer cached docs.
+use `--force` only when remote has changed.
+"""

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/llm_api_scope.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-api-scope
-Version: 0.6.1
+Version: 0.8.0
 Summary: read and cache structured documents from remote for LLM agents
 Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
 License: MIT License
@@ -79,6 +79,17 @@ 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.
 
+### skill
+
+output a combined command reference and strategy guide for AI agents.
+
+run `apiscope skill` to get a single document that covers every subcommand and
+how they fit together. the strategy guide classifies commands into management and
+usage groups, lists prerequisites in ABNF (RFC 5234), and provides workflow
+patterns with requirement levels (RFC 2119).
+
+agents read this output once at onboarding instead of running `--help` repeatedly.
+
 ### repo
 
 sync documentation directories from any git repository to a local cache.

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/llm_api_scope.egg-info/SOURCES.txt

@@ -24,6 +24,10 @@ apiscope/rfc/parse_txt.py
 apiscope/rfc/parse_xml.py
 apiscope/rfc/schema.py
 apiscope/rfc/search.py
+apiscope/skill/__init__.py
+apiscope/skill/_usage.py
+apiscope/skill/app.py
+apiscope/skill/docs.py
 llm_api_scope.egg-info/PKG-INFO
 llm_api_scope.egg-info/SOURCES.txt
 llm_api_scope.egg-info/dependency_links.txt

{llm_api_scope-0.6.1 → llm_api_scope-0.8.0}/pyproject.toml

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