Metadata-Version: 2.4
Name: llm-api-scope
Version: 0.12.1
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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: pyyaml>=6.0.3
Requires-Dist: httpx2>=2.13.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.

a source link is registered once; a repeated link fails, even under another name or type.
a private source in the home configuration uses an absolute path, and a project source uses a path relative to the project root.

six 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
- `arxiv` reads one arXiv paper by its canonical identifier

```bash
apiscope add docs https://example.test/docs/llms.txt --type llmstxt
apiscope add api https://github.com/example/api.git/docs@main --type repo
apiscope add paper 1706.03762 --type arxiv
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 and the `no_proxy` bypass list.

```json
{
  "setting": {
    "public": {"doc_ttl": 7},
    "local": {
      "proxy": "http://proxy.example.test:8080",
      "no_proxy": "internal.example.test,localhost"
    }
  }
}
```

the HTTP client uses only the configured `[proxy]` and `[no_proxy]` and ignores environment proxy variables.
for repository operations, apiscope passes configured proxy settings to `git` and `gh`; when `[proxy]` is unset, it does not set or clear their proxy.
`[no_proxy]` is a comma-separated list of hosts, domains, or `*` that bypasses the configured proxy.

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>]
```

`arxiv` accepts a canonical identifier such as `1706.03762` or `hep-th/9901001`; append `vN` for a fixed version. URL forms are not accepted.

### 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, llmstxt, or arxiv.

### 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, and a subpath selects files with a sparse checkout.
`llmstxt` reads the index page, downloads the pages it lists, and skips a failed page.
`arxiv` prefers structured HTML, falls back to TeX source, and does not parse PDF-, PostScript-, or DVI-only submissions.

### 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.

### bookmark

save a named reference and reopen it later:

```bash
apiscope bookmark add <id> <mode> <target>... --description <text>
apiscope bookmark list [<group>]
apiscope bookmark use <id>
apiscope bookmark remove <id>
apiscope bookmark prune [--invalid]
```

mode is file, view, read, or group; a group takes five to nine member ids.
bookmarks live in a global file and a project file, and the project wins.

### 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
