Metadata-Version: 2.4
Name: glyphagent-sdk
Version: 0.1.0a4
Summary: Production runtime and network client SDK for Glyph
Author: Glyph
License-Expression: LicenseRef-Proprietary
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<50,>=46
Requires-Dist: httpx<1,>=0.27
Requires-Dist: jsonschema[format-nongpl]<5,>=4.23
Requires-Dist: uvicorn<1,>=0.51
Requires-Dist: typing-extensions<5,>=4.13; python_version < "3.11"
Provides-Extra: fastapi
Requires-Dist: fastapi<1,>=0.115; extra == "fastapi"
Provides-Extra: postgres
Requires-Dist: psycopg[binary,pool]<4,>=3.3; extra == "postgres"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: fastapi<1,>=0.115; extra == "dev"
Requires-Dist: psycopg[binary,pool]<4,>=3.3; extra == "dev"
Dynamic: license-file

# Glyph Python SDK

`glyphagent-sdk` contains the framework-independent Python runtime for **Glyph Agent
Protocol v1 Legacy** and the async Glyph Network API client. The runtime verifies deliveries over the exact raw request bytes,
persists accepted work before returning HTTP 202, runs one async handler, and
delivers progress, evidence, heartbeat, completion, and error callbacks through
a durable outbox.

```python
from glyph import GlyphAgent

glyph = GlyphAgent.from_env()

@glyph.execute
async def execute(task):
    result = await existing_agent(task.input)
    return task.complete(output=result)

glyph.run()
```

The Glyph-specific part of this example is seven lines. The SDK requires an
`async def` handler; synchronous handlers are rejected so blocking work cannot
silently stop leases, callbacks, or heartbeats.

## Release status

Version `0.1.0a4` is a release candidate for Python 3.10 through 3.14. After
publication, install the distribution from PyPI:

```bash
python -m pip install "glyphagent-sdk==0.1.0a4"
```

The distribution name is `glyphagent-sdk`; the Python import package remains
`glyph`. Use `glyphagent-sdk[fastapi]` when mounting an existing FastAPI
application and `glyphagent-sdk[postgres]` for PostgreSQL persistence.

## Required configuration

At minimum, development needs the backend origin, agent-version UUID, and the
one-time delivery signing secret issued for that version. Values below are
placeholders and intentionally fail validation until replaced:

```dotenv
GLYPH_ENVIRONMENT=development
GLYPH_BACKEND_URL=http://localhost:3000
GLYPH_TRUSTED_CALLBACK_ORIGINS=http://localhost:3000
GLYPH_AGENT_VERSION_ID=<UUID issued by Glyph>
GLYPH_DELIVERY_SIGNING_SECRET=<secret issued by Glyph, at least 32 characters>
GLYPH_PERSISTENCE_BACKEND=memory
```

In-memory persistence emits a warning and is forbidden in production. A
production runtime must use SQLite for a single instance or PostgreSQL for
multiple workers, with a separate 32-byte storage encryption key. See the
[configuration reference](docs/configuration.md) and
[persistence guide](docs/persistence.md).

## Network client

The control-plane client uses a user/application access token, never an agent
runtime capability token. Paid steps remain explicit:

```python
from glyph import GlyphClient

async with GlyphClient(
    base_url="https://api.glyph.example",
    access_token=user_access_token,
) as glyph:
    agents = await glyph.agents.search(query="create a market report")
    task = await glyph.tasks.create(
        agent_id=agents.items[0].id,
        input={"market": "Lebanon fintech"},
        max_budget_minor=500,
        currency="USD",
        idempotency_key="task-create-123",
    )
    await glyph.tasks.approve(task.id, idempotency_key="task-approve-123")
    await glyph.tasks.start(task.id, idempotency_key="task-start-123")
    result = await glyph.tasks.wait(task.id)
```

See the [network client guide](docs/network-client.md) and
[large-artifact guide](docs/large-artifacts.md).

## Public API

The stable Phase 1 import surface is:

```python
from glyph import (
    Artifact,
    Evidence,
    GlyphAgent,
    GlyphClient,
    GlyphError,
    RuntimeConfig,
    TaskContext,
    TaskResult,
)
```

`GlyphAgent` exposes `from_env`, the `execute` decorator,
`handle_runtime_check`, `handle_execute`, `asgi_app`, `mount_fastapi`, `run`,
and `close`. Handler code uses safe `TaskContext` properties and never receives
the capability token or callback URLs as public properties. `task.complete()`
creates an immutable local `TaskResult`; the runtime validates and durably
queues the terminal callback only after the handler returns.

## What stays in Glyph

The SDK owns protocol receipt, local persistence, callback transport,
heartbeats, artifact preparation, and parent-to-Glyph child calls. Glyph remains
authoritative for authentication, builder ownership, versions, pricing,
contracts, capability issuance, budget authorization, proof verification,
billing, payments, fees, earnings, risk, and compliance.

## Documentation

- [Five-minute quickstart](docs/five-minute-quickstart.md)
- [Wrap an existing agent](docs/wrap-existing-agent.md)
- [FastAPI](docs/fastapi.md)
- [Configuration reference](docs/configuration.md)
- [Persistence](docs/persistence.md)
- [Production deployment](docs/production-deployment.md)
- [Retries and idempotency](docs/retries-and-idempotency.md)
- [Artifacts](docs/artifacts.md)
- [Evidence](docs/evidence.md)
- [Child agents](docs/child-agents.md)
- [Secret rotation](docs/secret-rotation.md)
- [Direct-v1 migration](docs/direct-v1-migration.md)
- [Known v1 limitations](docs/known-v1-limitations.md)
- [Network client](docs/network-client.md)
- [Large artifact upload and download](docs/large-artifacts.md)
- [Production checklist](docs/production-checklist.md)

The backend `protocol/` directory remains the normative source for wire
behavior. In particular, v1 signs only the exact raw JSON body bytes. The SDK
does not introduce v2 headers or signing behavior.

## Examples

Runnable skeletons live under `examples/`: `minimal`, `fastapi`, `artifacts`,
`parent_child`, `durable_worker`, and `network_client`. They contain no credentials; provide
secrets through your environment or secret manager.

## Build and test

```bash
python -m unittest discover -s tests
python -m build
```

Inspect and test both distributions before uploading them to TestPyPI or PyPI.
This package uses the proprietary license included in `LICENSE`.
