general-augment-sdk 0.1.0__tar.gz

general_augment_sdk-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+packages/cli/uv.lock
+
+# Environment
+.env
+.env.local
+.env.gcp
+hermes-tenants/
+
+# Secrets
+*.pem
+*.key
+*.p12
+*.pfx
+.jks
+service-account.json
+.clerk/
+
+# Docker
+*.log
+docker-data/
+
+# IDE
+.idea/
+.vscode/
+
+# Build
+build/
+dist/
+*.egg-info/
+node_modules/
+.next/
+dashboard/.vercel/
+coverage/
+playwright-report/
+test-results/
+*.tsbuildinfo
+artifacts/
+dashboard/artifacts/
+
+# Kubernetes secrets
+k8s/secrets/*
+!k8s/secrets/.gitkeep
+
+# OS
+.DS_Store
+.vercel

general_augment_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,14 @@
+# Python SDK Agent Instructions
+
+These instructions apply under `packages/python-sdk/`.
+
+Inherit [`packages/AGENTS.md`](../AGENTS.md) and the repo root
+[`AGENTS.md`](../../AGENTS.md).
+
+## Scope
+
+- This package directory keeps a historical name. Public docs and examples should
+  describe General Augment and the `genaug` import path.
+- Use current hosted endpoints, `genaug-agent.yaml`, and `/v1/responses`-aligned flows in
+  examples and READMEs.
+- Update docs plus tests when public behavior changes.

general_augment_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: general-augment-sdk
+Version: 0.1.0
+Summary: Python SDK for the General Augment admin and integration APIs.
+Project-URL: Documentation, https://docs.generalaugment.com
+Project-URL: Source, https://github.com/Bikz/general-augment-platform
+Author: General Augment
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pyyaml>=6.0.0
+Description-Content-Type: text/markdown
+
+# General Augment Python SDK
+
+Backend SDK for General Augment app integrations. Use it from trusted server code.
+Project-scoped keys are for app traffic such as Responses and memory calls. Admin and
+setup helpers require a management/admin-capable key and send it as `X-Admin-Key`.
+
+During private beta, package publishing may not be available in every package index. If
+installing the package fails, use the repository package path for local tests or raw HTTP
+examples in the public docs until `scripts/package-registry-readiness.py` reports the
+expected package version as published.
+
+```bash
+pip install general-augment-sdk
+```
+
+```python
+import os
+
+from genaug import (
+    GeneralAugmentClient,
+    __version__,
+    response_output_text,
+    response_structured_output,
+)
+
+client = GeneralAugmentClient(
+    api_key=os.environ["GENAUG_API_KEY"],
+    base_url=os.getenv("GENAUG_API_BASE_URL", "https://api.generalaugment.com"),
+)
+
+print(f"General Augment SDK {__version__}")
+```
+
+## Responses
+
+```python
+response = client.create_response(
+    {
+        "model": "balanced",
+        "user": "app-user-123",
+        "input": "Reply with a concise onboarding summary.",
+        "metadata": {"feature": "onboarding"},
+    },
+    idempotency_key="onboarding-turn-1",
+    request_id="req_app_123",
+)
+
+print(response_output_text(response))
+```
+
+Structured output:
+
+```python
+structured_response = client.create_response(
+    {
+        "model": "balanced",
+        "user": "app-user-123",
+        "input": "Extract the user's preference: window seat.",
+        "text": {
+            "format": {
+                "type": "json_schema",
+                "name": "preference",
+                "strict": True,
+                "schema": {
+                    "type": "object",
+                    "required": ["seat"],
+                    "properties": {"seat": {"type": "string"}},
+                    "additionalProperties": False,
+                },
+            }
+        },
+    }
+)
+
+preference = response_structured_output(structured_response)
+```
+
+Streaming:
+
+```python
+for event in client.stream_response(
+    {
+        "model": "balanced",
+        "user": "app-user-123",
+        "input": "Draft a two sentence welcome message.",
+    }
+):
+    if event["event"] == "response.output_text.delta":
+        print(event["data"].get("delta", ""), end="")
+```
+
+## Memory
+
+```python
+stored = client.store_memory(
+    {
+        "user_id": "app-user-123",
+        "fact": "User prefers window seats",
+        "fact_type": "preference",
+        "importance_score": 0.9,
+        "idempotency_key": "memory-window-seat-1",
+    }
+)
+
+client.search_memory({"user_id": "app-user-123", "query": "seat preference"})
+client.memory_profile("app-user-123")
+client.delete_memory(str(stored["memory_id"]), user_id="app-user-123")
+client.purge_user_memory("app-user-123")
+```
+
+## Usage
+
+```python
+usage = client.usage("project_123", start_date="2026-04-01", end_date="2026-04-24")
+print(usage["totals"])
+```
+
+## Error Handling
+
+```python
+from genaug import GeneralAugmentAPIError
+
+try:
+    client.create_response({"model": "balanced", "input": "Hello"})
+except GeneralAugmentAPIError as exc:
+    if exc.reason == "rate_limit_exceeded":
+        print(f"Retry after {exc.retry_after} seconds")
+    print(exc.request_id, exc.trace_id, exc.detail)
+```
+
+`GeneralAugmentAPIError` preserves the HTTP status, stable `reason`/`code` when the
+API returns one, `Retry-After`, `X-RateLimit-*`, request/trace IDs, and the decoded JSON
+body. Existing code that only reads `status_code` or `detail` keeps working.
+
+## Local Tests
+
+Run the local mock server and point the SDK at it:
+
+```bash
+uv run --project packages/cli genaug mock --host 127.0.0.1 --port 8787 --quiet
+export GENAUG_API_BASE_URL="http://127.0.0.1:8787"
+export GENAUG_API_KEY="local-test"
+PYTHONPATH=src python examples/contract_test.py
+```
+
+The contract example covers a Responses turn plus memory store/search against the same
+deterministic routes used by app backend CI.
+
+## Other Helpers
+
+The SDK also includes `create_project_from_config`, `register_openapi_tools`,
+`link_user`, `usage`, and `test_agent` for admin and integration workflows.

general_augment_sdk-0.1.0/README.md

@@ -0,0 +1,152 @@
+# General Augment Python SDK
+
+Backend SDK for General Augment app integrations. Use it from trusted server code.
+Project-scoped keys are for app traffic such as Responses and memory calls. Admin and
+setup helpers require a management/admin-capable key and send it as `X-Admin-Key`.
+
+During private beta, package publishing may not be available in every package index. If
+installing the package fails, use the repository package path for local tests or raw HTTP
+examples in the public docs until `scripts/package-registry-readiness.py` reports the
+expected package version as published.
+
+```bash
+pip install general-augment-sdk
+```
+
+```python
+import os
+
+from genaug import (
+    GeneralAugmentClient,
+    __version__,
+    response_output_text,
+    response_structured_output,
+)
+
+client = GeneralAugmentClient(
+    api_key=os.environ["GENAUG_API_KEY"],
+    base_url=os.getenv("GENAUG_API_BASE_URL", "https://api.generalaugment.com"),
+)
+
+print(f"General Augment SDK {__version__}")
+```
+
+## Responses
+
+```python
+response = client.create_response(
+    {
+        "model": "balanced",
+        "user": "app-user-123",
+        "input": "Reply with a concise onboarding summary.",
+        "metadata": {"feature": "onboarding"},
+    },
+    idempotency_key="onboarding-turn-1",
+    request_id="req_app_123",
+)
+
+print(response_output_text(response))
+```
+
+Structured output:
+
+```python
+structured_response = client.create_response(
+    {
+        "model": "balanced",
+        "user": "app-user-123",
+        "input": "Extract the user's preference: window seat.",
+        "text": {
+            "format": {
+                "type": "json_schema",
+                "name": "preference",
+                "strict": True,
+                "schema": {
+                    "type": "object",
+                    "required": ["seat"],
+                    "properties": {"seat": {"type": "string"}},
+                    "additionalProperties": False,
+                },
+            }
+        },
+    }
+)
+
+preference = response_structured_output(structured_response)
+```
+
+Streaming:
+
+```python
+for event in client.stream_response(
+    {
+        "model": "balanced",
+        "user": "app-user-123",
+        "input": "Draft a two sentence welcome message.",
+    }
+):
+    if event["event"] == "response.output_text.delta":
+        print(event["data"].get("delta", ""), end="")
+```
+
+## Memory
+
+```python
+stored = client.store_memory(
+    {
+        "user_id": "app-user-123",
+        "fact": "User prefers window seats",
+        "fact_type": "preference",
+        "importance_score": 0.9,
+        "idempotency_key": "memory-window-seat-1",
+    }
+)
+
+client.search_memory({"user_id": "app-user-123", "query": "seat preference"})
+client.memory_profile("app-user-123")
+client.delete_memory(str(stored["memory_id"]), user_id="app-user-123")
+client.purge_user_memory("app-user-123")
+```
+
+## Usage
+
+```python
+usage = client.usage("project_123", start_date="2026-04-01", end_date="2026-04-24")
+print(usage["totals"])
+```
+
+## Error Handling
+
+```python
+from genaug import GeneralAugmentAPIError
+
+try:
+    client.create_response({"model": "balanced", "input": "Hello"})
+except GeneralAugmentAPIError as exc:
+    if exc.reason == "rate_limit_exceeded":
+        print(f"Retry after {exc.retry_after} seconds")
+    print(exc.request_id, exc.trace_id, exc.detail)
+```
+
+`GeneralAugmentAPIError` preserves the HTTP status, stable `reason`/`code` when the
+API returns one, `Retry-After`, `X-RateLimit-*`, request/trace IDs, and the decoded JSON
+body. Existing code that only reads `status_code` or `detail` keeps working.
+
+## Local Tests
+
+Run the local mock server and point the SDK at it:
+
+```bash
+uv run --project packages/cli genaug mock --host 127.0.0.1 --port 8787 --quiet
+export GENAUG_API_BASE_URL="http://127.0.0.1:8787"
+export GENAUG_API_KEY="local-test"
+PYTHONPATH=src python examples/contract_test.py
+```
+
+The contract example covers a Responses turn plus memory store/search against the same
+deterministic routes used by app backend CI.
+
+## Other Helpers
+
+The SDK also includes `create_project_from_config`, `register_openapi_tools`,
+`link_user`, `usage`, and `test_agent` for admin and integration workflows.

general_augment_sdk-0.1.0/examples/contract_test.py

@@ -0,0 +1,54 @@
+"""Mock-backed contract example for the General Augment Python SDK.
+
+Run `uv run --project packages/cli genaug mock --host 127.0.0.1 --port 8787 --quiet`
+from the repository root, then run this file with GENAUG_API_BASE_URL pointed at the
+mock server.
+"""
+
+from __future__ import annotations
+
+import os
+
+from genaug import GeneralAugmentClient, response_output_text
+
+
+def main() -> None:
+    """Exercise Responses and memory against the local mock contract."""
+    client = GeneralAugmentClient(
+        api_key=os.getenv("GENAUG_API_KEY", "local-test"),
+        base_url=os.getenv("GENAUG_API_BASE_URL", "http://127.0.0.1:8787"),
+    )
+
+    response = client.create_response(
+        {
+            "model": "balanced",
+            "user": "sdk-contract-user",
+            "input": "Reply exactly with: local-mock-ok",
+            "metadata": {"fixture": "sdk-contract"},
+        },
+        idempotency_key="sdk-contract-turn-1",
+        request_id="req_sdk_contract_py",
+    )
+    assert response["status"] == "completed"
+    assert response_output_text(response)
+
+    stored = client.store_memory(
+        {
+            "user_id": "sdk-contract-user",
+            "fact": "User prefers window seats",
+            "fact_type": "preference",
+            "idempotency_key": "sdk-contract-memory-1",
+        }
+    )
+    assert stored.get("memory_id") or stored.get("id")
+
+    search = client.search_memory(
+        {"user_id": "sdk-contract-user", "query": "seat preference", "limit": 3}
+    )
+    assert isinstance(search.get("facts"), list)
+
+    print("General Augment Python SDK contract example passed.")
+
+
+if __name__ == "__main__":
+    main()

general_augment_sdk-0.1.0/examples/quickstart.py

@@ -0,0 +1,40 @@
+"""Minimal General Augment Python SDK quickstart."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from genaug import GeneralAugmentClient, response_output_text
+from genaug.identity import link_user
+from genaug.tools import register_from_openapi
+
+
+def main() -> None:
+    """Deploy a config, register tools, link a user, and call Responses."""
+    api_key = os.environ["GENAUG_API_KEY"]
+    spec_url = os.environ["OPENAPI_SPEC_URL"]
+    with GeneralAugmentClient(api_key=api_key) as client:
+        project = client.deploy_config_file(Path("genaug-agent.yaml"))
+        register_from_openapi(spec_url, client=client, project_id=str(project["id"]))
+        link_user(
+            client,
+            str(project["id"]),
+            phone="+15551234567",
+            app_user_id="app-user-123",
+        )
+        response = client.create_response(
+            {
+                "model": "balanced",
+                "user": "app-user-123",
+                "input": "Reply with a concise onboarding summary.",
+                "metadata": {"feature": "sdk-quickstart"},
+            },
+            idempotency_key="sdk-quickstart-turn-1",
+            request_id="req_sdk_quickstart",
+        )
+        print(response_output_text(response))
+
+
+if __name__ == "__main__":
+    main()

general_augment_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "general-augment-sdk"
+version = "0.1.0"
+description = "Python SDK for the General Augment admin and integration APIs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "General Augment" }]
+dependencies = [
+    "httpx>=0.28.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.urls]
+Documentation = "https://docs.generalaugment.com"
+Source = "https://github.com/Bikz/general-augment-platform"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/genaug"]

general_augment_sdk-0.1.0/src/genaug/__init__.py

@@ -0,0 +1,20 @@
+"""General Augment Python SDK public import path."""
+
+from genaug.agent import AgentClient
+from genaug.client import (
+    GeneralAugmentAPIError,
+    GeneralAugmentClient,
+    response_output_text,
+    response_structured_output,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentClient",
+    "GeneralAugmentAPIError",
+    "GeneralAugmentClient",
+    "__version__",
+    "response_output_text",
+    "response_structured_output",
+]

general_augment_sdk-0.1.0/src/genaug/agent.py

@@ -0,0 +1,48 @@
+"""Agent test helpers for General Augment SDK users."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from genaug.client import GeneralAugmentClient
+
+
+class AgentClient:
+    """Convenience wrapper scoped to one General Augment project."""
+
+    def __init__(self, client: GeneralAugmentClient, project_id: str) -> None:
+        """Initialize a project-scoped agent client."""
+        self.client = client
+        self.project_id = project_id
+
+    def test(
+        self,
+        message: str,
+        *,
+        phone_e164: str = "+15550000000",
+        channel: str = "whatsapp",
+    ) -> dict[str, Any]:
+        """Send a test message to the configured agent."""
+        return self.client.test_agent(
+            self.project_id,
+            message,
+            phone_e164=phone_e164,
+            channel=channel,
+        )
+
+
+def test(
+    client: GeneralAugmentClient,
+    project_id: str,
+    message: str,
+    *,
+    phone_e164: str = "+15550000000",
+    channel: str = "whatsapp",
+) -> dict[str, Any]:
+    """Send a one-off test message to a General Augment project."""
+    return client.test_agent(
+        project_id,
+        message,
+        phone_e164=phone_e164,
+        channel=channel,
+    )