Metadata-Version: 2.4
Name: abstract_toolserver
Version: 0.0.1
Summary: The abstract_* ecosystem exposed as an API-callable AI toolset: functions become self-describing Flask endpoints with /endpoints discovery and ?help.
Home-page: https://github.com/AbstractEndeavors/abstract_toolserver
Author: putkoff
Author-email: partners@abstractendeavors.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: abstract_flask
Requires-Dist: abstract_utilities
Provides-Extra: files
Requires-Dist: abstract_search; extra == "files"
Requires-Dist: abstract_paths; extra == "files"
Provides-Extra: web
Requires-Dist: abstract_webtools; extra == "web"
Provides-Extra: media
Requires-Dist: abstract_ocr; extra == "media"
Requires-Dist: abstract_pandas; extra == "media"
Requires-Dist: media_intelligence; extra == "media"
Provides-Extra: ai
Requires-Dist: abstract_ai; extra == "ai"
Provides-Extra: db
Requires-Dist: abstract_database; extra == "db"
Provides-Extra: ui
Requires-Dist: abstract_clicks; extra == "ui"
Requires-Dist: abstract_windows; extra == "ui"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# abstract_toolserver

The `abstract_*` ecosystem exposed as an **API-callable AI toolset** — every tool
is a plain Python function turned into a self-describing HTTP endpoint by
[`abstract_flask`](https://github.com/AbstractEndeavors/abstract_flask). A portable
tool layer any model (Claude, hugpy, …) can drive over HTTP instead of being
bound to one runtime's tool harness.

## Run it

```bash
pip install abstract_toolserver          # + the extras you want to expose
python -m abstract_toolserver            # HOST/PORT/DEBUG from TOOLSERVER_* env
```

```python
from abstract_toolserver import get_toolserver_app
app = get_toolserver_app()               # a normal Flask/WSGI app
```

## Self-describing surface

The app auto-mounts introspection endpoints (from `abstract_flask`):

| Endpoint | What it gives an LLM |
|---|---|
| `GET /prefixes` | the tool categories (`/fs`, `/db`, `/ui`, …) |
| `GET /endpoints` | every tool as `{endpoint, url, methods}` |
| `GET /<cat>/<tool>?help=true` | that tool's signature/help |

Call a tool with JSON; unknown keys are pruned to the function signature, and the
reply is `{"result": ...}` (or `{"error": ...}`). Discover-and-dispatch from a
client is already provided by `abstract_apis.make_endpoint_call`.

```bash
curl -s localhost:5000/fs/count_tokens -d '{"text":"hello world"}'
# {"result": 2}
curl -s localhost:5000/db/schema           # {"result": {table: [cols...]}}
curl -s 'localhost:5000/db/query?help=true'
```

## Tool categories

| Prefix | Tools | Backend |
|---|---|---|
| `/fs` | search, read_span, extract, read_file, write_file, read_json, find_keys, find_paths, glob, imports, find_content | abstract_search, abstract_utilities, abstract_paths |
| `/text` | count_tokens, chunk, detect_language | abstract_utilities |
| `/web` | text, links, attributes | abstract_webtools |
| `/media` | ocr_image, pdf_text, summarize, keywords, transcribe | abstract_ocr, abstract_pandas, media_intelligence |
| `/ai` | query | abstract_ai |
| `/db` | tables, schema, columns, fetch, **query** | abstract_database |
| `/sys` | run_cmd | stdlib (gated) |
| `/ui` | capture, monitors, ocr, windows, **click_verify** | abstract_clicks, abstract_windows |

## Safety gates

Backends load lazily, so the server boots on a headless box and a missing backend
errors only when its tool is called. Beyond that:

- **`/db/query`** — read-only gate: rejects anything that isn't a single
  `SELECT`/`WITH`, blocks stacked statements and data-modifying keywords. Use
  `/db/fetch` (identifier-composed, params-not-SQL) as the default read path.
- **`/sys/run_cmd`** — disabled unless `TOOLSERVER_CMD_ALLOWLIST=ls,grep,…` is set;
  only allowlisted binaries run.
- **`/fs/read_file` · `/fs/write_file`** — local-only; the underlying SSH/remote
  kwargs are never exposed at the boundary.
- **`/ui/click_verify`** — the click→observe→**verify** loop: locate (text or image
  template) → click → re-capture → report whether the screen (or a `region`)
  changed. The half most tool APIs lack.

## Configuration

| Env var | Purpose |
|---|---|
| `TOOLSERVER_HOST` / `TOOLSERVER_PORT` / `TOOLSERVER_DEBUG` | bind + debug |
| `TOOLSERVER_CMD_ALLOWLIST` | comma-separated binaries `/sys/run_cmd` may run |
| `SOLCATCHER_POSTGRESQL_*` | DB connection (via abstract_database) |
