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

{llm_api_scope-0.6.0/llm_api_scope.egg-info → llm_api_scope-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-api-scope
-Version: 0.6.0
+Version: 0.7.0
 Summary: read and cache structured documents from remote for LLM agents
 Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
 License: MIT License

{llm_api_scope-0.6.0 → llm_api_scope-0.7.0}/apiscope/config.py

@@ -153,7 +153,12 @@ def get_config() -> Config:
 
     # 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():
+    if project_config_path is not None:
+        if not project_config_path.exists() or project_config_path.stat().st_size == 0:
+            # create default project config if not exists
+            project_config_path.write_text(
+                json.dumps({"$schema": DEFAULT_CONFIG_SCHEMA_PATH.as_uri()}, indent=2) + "\n"
+            )
         project_config = Config.model_validate_json(project_config_path.read_text())
         return global_config.merge(project_config)
 

{llm_api_scope-0.6.0 → llm_api_scope-0.7.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.0 → llm_api_scope-0.7.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.7.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.7.0/apiscope/skill/_usage.py

@@ -0,0 +1,72 @@
+# 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
+"""

llm_api_scope-0.7.0/apiscope/skill/app.py

@@ -0,0 +1,19 @@
+# apiscope/skill/app.py
+
+import typer
+
+from apiscope.skill._usage import USAGE_TEXT
+from apiscope.skill.docs import STRATEGY_GUIDE
+
+app = typer.Typer(help="output usage guide for ai agents")
+
+
+@app.callback(invoke_without_command=True)
+def skill_callback() -> None:
+    typer.echo("=== COMMAND REFERENCE ===")
+    typer.echo()
+    typer.echo(USAGE_TEXT)
+    typer.echo()
+    typer.echo("=== STRATEGY GUIDE ===")
+    typer.echo()
+    typer.echo(STRATEGY_GUIDE)

llm_api_scope-0.7.0/apiscope/skill/docs.py

@@ -0,0 +1,111 @@
+# 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.
+"""

{llm_api_scope-0.6.0 → llm_api_scope-0.7.0/llm_api_scope.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llm-api-scope
-Version: 0.6.0
+Version: 0.7.0
 Summary: read and cache structured documents from remote for LLM agents
 Author-email: D7x7z49 <85430783+D7x7z49@users.noreply.github.com>
 License: MIT License

{llm_api_scope-0.6.0 → llm_api_scope-0.7.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.0 → llm_api_scope-0.7.0}/pyproject.toml

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