Metadata-Version: 2.4
Name: fathom-skill
Version: 0.1.0
Summary: Python SDK for writing Fathom skills — typed Ctx, fetch+secrets helpers, manifest types.
Project-URL: Homepage, https://github.com/darklake-ai/fathom-skill-py
Project-URL: Repository, https://github.com/darklake-ai/fathom-skill-py
Project-URL: Issues, https://github.com/darklake-ai/fathom-skill-py/issues
Author: darklake.ai
License: MIT
License-File: LICENSE
Keywords: agent,ai,darklake,fathom,llm,plugin,skill
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# fathom-skill

Python SDK for writing [Fathom](https://github.com/darklake-ai/fathom)
skills. Typed `Ctx`, fetch + secret helpers, manifest types — small
package, zero runtime dependencies.

## Install

```sh
pip install fathom-skill
```

Requires Python 3.10+ and the Fathom gateway at v0.8.0 or later
(earlier gateways only run Node skills).

## Quick start

```python
# my-skill/index.py
from fathom_skill import Ctx, require_fetch, require_secret


async def search(params: dict, ctx: Ctx) -> dict:
    fetch = require_fetch(ctx)
    res = await fetch(
        f"https://api.example.com/search?q={params['query']}",
        attach=[{"type": "bearer", "secret": "EXAMPLE_API_KEY"}],
    )
    return {"body": res["body"]}
```

```yaml
# my-skill/skill.manifest.yaml
name: my-skill
version: "1.0.0"
author: you@example.com
signature: ed25519:builtin
language: python                  # tells Fathom to run via runner.py
permissions:
  network:
    - GET https://api.example.com/*
  secrets:
    - EXAMPLE_API_KEY
tools:
  - name: search
    function: search
    description: Search the example API for a query.
```

Drop this directory into your Fathom `skills/` folder. The agent
loads it on next start.

## Sync skills

Functions don't have to be `async`. The runner detects sync vs async
via `inspect.iscoroutinefunction` and dispatches accordingly:

```python
def echo(params: dict, ctx: Ctx) -> dict:
    return params
```

If your skill makes HTTP calls via `ctx.fetch` you need `async def`
because `fetch` is awaitable. Pure-compute skills can stay sync.

## Credential attaches

```python
from fathom_skill import BearerAttach, HeaderAttach, BasicAttach, GoogleOauthAttach
```

| Type | What it does |
|---|---|
| `bearer` | `Authorization: Bearer <secret>` |
| `header` | Arbitrary header with optional template (`Bot ${secret}` etc.) |
| `basic` | `Authorization: Basic base64(user:pass)` |
| `google-oauth` | Refresh-token rotation; injects fresh access token |

## Manifest typing

```python
from fathom_skill import SkillManifest

manifest: SkillManifest = {
    "name": "my-skill",
    "version": "1.0.0",
    "author": "you@example.com",
    "signature": "ed25519:builtin",
    "language": "python",
    "permissions": {
        "network": ["GET https://api.example.com/*"],
        "secrets": ["EXAMPLE_API_KEY"],
    },
    "tools": [
        {
            "name": "search",
            "function": "search",
            "description": "Search the example API for a query.",
        },
    ],
}
```

## Reference

- `Ctx` — runtime context protocol with optional `get_secret` + `fetch`.
- `require_fetch(ctx)` / `require_secret(ctx, name)` — narrow to non-optional, raise with a useful message if the runtime didn't provide it.
- `EgressAttach` union — `BearerAttach | HeaderAttach | BasicAttach | GoogleOauthAttach`.
- `SkillManifest`, `SkillPermissions`, `SkillTool` — typed mirror of `skill.manifest.yaml`.

## See also

- [`fathom-sdk`](https://pypi.org/project/fathom-sdk/) — Python client for the Fathom gateway (for *calling* the agent from your code, distinct from skills which are *invoked by* the agent).
- [`@darklake.ai/fathom-skill`](https://www.npmjs.com/package/@darklake.ai/fathom-skill) — the sibling SDK for TypeScript skills.

## License

MIT — see [LICENSE](./LICENSE).
