Metadata-Version: 2.4
Name: general-augment-sdk
Version: 0.5.5
Summary: Python SDK for General Augment, the agent backend for your app.
Project-URL: Homepage, https://generalaugment.com
Project-URL: Documentation, https://docs.generalaugment.com
Project-URL: Source, https://github.com/LunarVentures/general-augment-platform
Project-URL: Issues, https://github.com/LunarVentures/general-augment-platform/issues
Author: General Augment
License-Expression: MIT
Keywords: agent-backend,ai-agents,general-augment,llm,memory,tools
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# General Augment Python SDK

General Augment is the easiest way to deploy a governed agent inside an existing authenticated app—with its users, permissions, memory, and tools already wired.

General Augment is the agent backend for your app.

This package is the server-side runtime client for `POST /v1/responses`. Configure Projects, Agents, identity, memory, capabilities, credentials, releases, and runtime keys with `genaug` or the General Augment dashboard. The SDK intentionally does not expose management-plane mutations.

## Install

```bash
pip install general-augment-sdk==0.5.5
```

Python 3.10+ is supported. Keep the Project runtime key on your app backend; never ship it to a browser or mobile client.

## Create a turn

```python
import os

from genaug import GeneralAugmentClient, response_output_text

with GeneralAugmentClient(
    api_key=os.environ["GENAUG_API_KEY"],
    project_id=os.environ["GENAUG_PROJECT_ID"],
    stream_timeout=300,
) as client:
    response = client.create_response(
        {
            "agent": "support",
            "user": authenticated_user.id,
            "input": "Where is my order?",
        },
        idempotency_key=f"support:{authenticated_user.id}:{message.id}",
    )

print(response_output_text(response))
```

Approval-gated turns return `status: "in_progress"` under the same response/run/trace identity.
Use the durable response read to update the customer transcript after approval:

```python
terminal = client.wait_for_response(response)
print(response_output_text(terminal))
```

`wait_for_response` polls `GET /v1/responses/{response_id}`; it never starts a second Agent turn or
tool effect. Use `retrieve_response(response["id"])` when your backend owns the polling schedule.

The CLI writes the key and its paired `GENAUG_PROJECT_ID` together. The SDK sends both so a stale or cross-Project key fails before Agent resolution. The `user` value must be the stable app-user identity declared by the Project’s trusted identity contract. General Augment resolves the exact Live release, Agent policy, capabilities, and per-user memory server-side.

## Stream a turn

```python
with GeneralAugmentClient(
    api_key=os.environ["GENAUG_API_KEY"],
    project_id=os.environ["GENAUG_PROJECT_ID"],
) as client:
    message_id = "app-message-456"  # Persist this with the app message.
    for event in client.stream_response(
        {
            "agent": "support",
            "user": authenticated_user.id,
            "input": "Cancel my last order",
        },
        idempotency_key=message_id,
    ):
        print(event.get("id"), event["event"], event["data"])
```

Streams are live with either an automatic or caller-supplied idempotency key. Supply and
persist the key when your app may reconnect; after a disconnect, retry the identical
request with that key and deduplicate replayed events by `event["id"]`. The stream deadline is
five minutes by default and is
configurable with `stream_timeout`; use `0` only when your backend provides its own
total deadline.

`GeneralAugmentAPIError` exposes `status_code`, `code`, `reason`, `request_id`, `retry_after`, and rate-limit metadata. Transient failures are retried with the same automatically generated idempotency key by default.

Keep `previous_response_id` state per stable `(user, agent)` pair. Switching Agents starts
or resumes that Agent's continuation chain; never send one Agent's response ID to another.
Cross-Agent continuity comes from release-granted shared user memory. Stream iteration
raises `GeneralAugmentAPIError` for both `event: error` and terminal `response.failed`
frames instead of leaving callers with an empty failed response.

Full reference: https://docs.generalaugment.com/sdk/reference/
