asgard-sdk 0.1.0__tar.gz

asgard_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Test
+        run: pytest

asgard_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: publish.yml
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

asgard_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

asgard_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

asgard_sdk-0.1.0/CLAUDE.md

@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+This project uses `uv` for dependency management and `pytest` for testing.
+
+```bash
+# Install dependencies (dev)
+uv pip install -e ".[dev]"
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/test_bot_provider.py
+
+# Run a single test
+uv run pytest tests/test_bot_provider.py::test_send_message_returns_reply
+
+# Run the CLI
+uv run asgard-cli --help
+
+# Build distribution
+uv build
+```
+
+There is no linter configured. Python version is pinned to 3.14 (see `.python-version`).
+
+## Architecture
+
+The SDK exposes two top-level clients, both using a shared `HttpCore` transport layer:
+
+- **`BotProviderClient`** ([src/asgard/bot_provider.py](src/asgard/bot_provider.py)) — conversational bot interface. Supports REST (`send_message`) and SSE streaming (`stream`), plus blob uploads.
+- **`FunctionAgentClient`** ([src/asgard/function_agent.py](src/asgard/function_agent.py)) — one-shot function agent. Supports JSON trigger and multipart form trigger.
+
+**Transport layer** ([src/asgard/_http.py](src/asgard/_http.py)): `HttpCore` builds URLs as `{host}/ns/{namespace}/bot-provider/{name}/{endpoint}`, injects `X-API-KEY` auth, and raises `AsgardError` on non-2xx responses.
+
+**SSE streaming** ([src/asgard/streaming.py](src/asgard/streaming.py)): `BotProviderStream` is a context manager and iterator that parses `data:` lines from the response, yields `GenericBotSseEvent` objects, stops on `RUN_DONE`, and raises `AsgardStreamError` on `RUN_ERROR`.
+
+**Models** ([src/asgard/models/](src/asgard/models/)): All Pydantic models extend `CamelModel` (from `_base.py`), which uses `alias_generator=to_camel` so Python snake_case fields serialize/deserialize as camelCase JSON automatically. Call `.model_dump(by_alias=True)` when sending to the API.
+
+**SSE event structure**: Every SSE event is a `GenericBotSseEvent` with an `event_type` (`SseEventType` enum) and a `fact` (`GenericBotSseEventFact`). The fact is a union object — only the field matching the event type is populated (e.g., `event.fact.message_delta` for `MESSAGE_DELTA` events).
+
+**CLI** ([src/asgard/cli.py](src/asgard/cli.py)): Interactive REPL (`--agent bot`) or one-shot runner (`--agent function`). `BotSession` dataclass tracks channel ID, transport mode, debug flag, and attached blob IDs across REPL turns. All config can come from env vars (`EDGE_SERVER_HOST`, `NAMESPACE`, `BOT_PROVIDER_NAME`, `BOT_PROVIDER_API_KEY`).
+
+**Testing**: Tests use `respx` to mock HTTP requests for REST calls, and `httpx.MockTransport` for SSE streaming tests (since `respx` doesn't support streaming). The `http_client` constructor parameter on both clients accepts an injected `httpx.Client` for test isolation.

asgard_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: asgard-sdk
+Version: 0.1.0
+Summary: Python SDK for Asgard Core API
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# asgard-sdk-python
+
+Python SDK for the Asgard Core API. Sync-first, with async extensibility in mind.
+
+## Installation
+
+```bash
+uv add asgard-sdk-python
+```
+
+Or for development:
+
+```bash
+uv sync --extra dev
+```
+
+## Requirements
+
+Python 3.11+
+
+## Quick Start
+
+### BotProviderClient
+
+```python
+from asgard import BotProviderClient, GenericBotMessage
+
+client = BotProviderClient(
+    host="http://localhost:8080",
+    namespace="my-ns",
+    bot_provider_name="my-bot",
+    api_key="secret",
+)
+
+# Send a message (REST)
+message = GenericBotMessage(custom_channel_id="ch-1", custom_message_id="m-1", text="hello")
+reply = client.send_message(message)
+for m in reply.messages:
+    print(m.text)
+
+# Stream a message (SSE)
+with client.stream(message) as stream:
+    for event in stream:
+        if event.event_type.value == "asgard.message.delta":
+            print(event.fact.message_delta.text, end="", flush=True)
+
+# Upload a blob
+with open("image.png", "rb") as f:
+    blobs = client.upload_blob(custom_channel_id="ch-1", file=f, filename="image.png", mime="image/png")
+```
+
+### FunctionAgentClient
+
+```python
+from asgard import FunctionAgentClient
+
+client = FunctionAgentClient(
+    host="http://localhost:8080",
+    namespace="my-ns",
+    bot_provider_name="my-agent",
+    api_key="secret",
+)
+
+result = client.trigger_json({"key": "value"})
+
+with open("data.csv", "rb") as f:
+    result = client.trigger_form({"key": "value"}, file=f, filename="data.csv", mime="text/csv")
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `EDGE_SERVER_HOST` | EdgeServer host URL |
+| `NAMESPACE` | Asgard namespace |
+| `BOT_PROVIDER_NAME` | Bot/agent name |
+| `BOT_PROVIDER_API_KEY` | API key |
+
+## CLI
+
+```bash
+# Bot interactive REPL (SSE by default)
+asgard-cli --host http://localhost:8080 --namespace default --bot my-bot --apikey secret
+
+# Switch to REST transport
+asgard-cli --host ... --namespace ... --bot ... --apikey ... --transport rest
+
+# Using env vars
+export EDGE_SERVER_HOST=http://localhost:8080
+export NAMESPACE=default
+export BOT_PROVIDER_NAME=my-bot
+export BOT_PROVIDER_API_KEY=secret
+asgard-cli
+
+# Function agent — JSON trigger
+asgard-cli --agent function --json-trigger \
+  --trigger-payload '{"key": "value"}' \
+  --host ... --namespace ... --bot ... --apikey ...
+
+# Function agent — Form trigger
+asgard-cli --agent function --form-trigger \
+  --trigger-payload '{"key": "value"}' \
+  --form-file ./data.csv --form-mime text/csv \
+  --host ... --namespace ... --bot ... --apikey ...
+```
+
+### Bot REPL commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/exit` / `/quit` | Exit |
+| `/transport sse\|rest` | Switch transport |
+| `/debug on\|off` | Toggle debug mode |
+| `/blob <path> [mime]` | Upload and attach a blob |
+| `/blobs` | Show attached blob IDs |
+| `/clear-blobs` | Clear attached blobs |
+| `/channel [id]` | Show or switch channel |
+| `/reset [text]` | Send RESET_CHANNEL action |
+
+## Error Handling
+
+```python
+from asgard import AsgardError, AsgardStreamError
+
+try:
+    reply = client.send_message(message)
+except AsgardError as e:
+    print(e.detail.message)  # human-readable error
+    print(e.detail.code)     # error code
+
+try:
+    with client.stream(message) as stream:
+        for event in stream:
+            ...
+except AsgardStreamError as e:
+    print(e.detail.message)
+```
+
+## Tool Call Consent
+
+```python
+from asgard import GenericBotMessage, ToolCallConsentResponseItem, ToolCallConsentResult, PostBackAction
+
+# After receiving a tool_call.consent event:
+consent_items = [
+    ToolCallConsentResponseItem(
+        tool_call_id="tc-1",
+        result=ToolCallConsentResult.ALLOW_ONCE,
+    )
+]
+
+response = GenericBotMessage(
+    custom_channel_id="ch-1",
+    custom_message_id="m-2",
+    action=PostBackAction.RESPONSE_TOOL_CALL_CONSENT,
+    tool_call_consents=consent_items,
+)
+reply = client.send_message(response)
+```

asgard_sdk-0.1.0/README.md

@@ -0,0 +1,160 @@
+# asgard-sdk-python
+
+Python SDK for the Asgard Core API. Sync-first, with async extensibility in mind.
+
+## Installation
+
+```bash
+uv add asgard-sdk-python
+```
+
+Or for development:
+
+```bash
+uv sync --extra dev
+```
+
+## Requirements
+
+Python 3.11+
+
+## Quick Start
+
+### BotProviderClient
+
+```python
+from asgard import BotProviderClient, GenericBotMessage
+
+client = BotProviderClient(
+    host="http://localhost:8080",
+    namespace="my-ns",
+    bot_provider_name="my-bot",
+    api_key="secret",
+)
+
+# Send a message (REST)
+message = GenericBotMessage(custom_channel_id="ch-1", custom_message_id="m-1", text="hello")
+reply = client.send_message(message)
+for m in reply.messages:
+    print(m.text)
+
+# Stream a message (SSE)
+with client.stream(message) as stream:
+    for event in stream:
+        if event.event_type.value == "asgard.message.delta":
+            print(event.fact.message_delta.text, end="", flush=True)
+
+# Upload a blob
+with open("image.png", "rb") as f:
+    blobs = client.upload_blob(custom_channel_id="ch-1", file=f, filename="image.png", mime="image/png")
+```
+
+### FunctionAgentClient
+
+```python
+from asgard import FunctionAgentClient
+
+client = FunctionAgentClient(
+    host="http://localhost:8080",
+    namespace="my-ns",
+    bot_provider_name="my-agent",
+    api_key="secret",
+)
+
+result = client.trigger_json({"key": "value"})
+
+with open("data.csv", "rb") as f:
+    result = client.trigger_form({"key": "value"}, file=f, filename="data.csv", mime="text/csv")
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `EDGE_SERVER_HOST` | EdgeServer host URL |
+| `NAMESPACE` | Asgard namespace |
+| `BOT_PROVIDER_NAME` | Bot/agent name |
+| `BOT_PROVIDER_API_KEY` | API key |
+
+## CLI
+
+```bash
+# Bot interactive REPL (SSE by default)
+asgard-cli --host http://localhost:8080 --namespace default --bot my-bot --apikey secret
+
+# Switch to REST transport
+asgard-cli --host ... --namespace ... --bot ... --apikey ... --transport rest
+
+# Using env vars
+export EDGE_SERVER_HOST=http://localhost:8080
+export NAMESPACE=default
+export BOT_PROVIDER_NAME=my-bot
+export BOT_PROVIDER_API_KEY=secret
+asgard-cli
+
+# Function agent — JSON trigger
+asgard-cli --agent function --json-trigger \
+  --trigger-payload '{"key": "value"}' \
+  --host ... --namespace ... --bot ... --apikey ...
+
+# Function agent — Form trigger
+asgard-cli --agent function --form-trigger \
+  --trigger-payload '{"key": "value"}' \
+  --form-file ./data.csv --form-mime text/csv \
+  --host ... --namespace ... --bot ... --apikey ...
+```
+
+### Bot REPL commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help |
+| `/exit` / `/quit` | Exit |
+| `/transport sse\|rest` | Switch transport |
+| `/debug on\|off` | Toggle debug mode |
+| `/blob <path> [mime]` | Upload and attach a blob |
+| `/blobs` | Show attached blob IDs |
+| `/clear-blobs` | Clear attached blobs |
+| `/channel [id]` | Show or switch channel |
+| `/reset [text]` | Send RESET_CHANNEL action |
+
+## Error Handling
+
+```python
+from asgard import AsgardError, AsgardStreamError
+
+try:
+    reply = client.send_message(message)
+except AsgardError as e:
+    print(e.detail.message)  # human-readable error
+    print(e.detail.code)     # error code
+
+try:
+    with client.stream(message) as stream:
+        for event in stream:
+            ...
+except AsgardStreamError as e:
+    print(e.detail.message)
+```
+
+## Tool Call Consent
+
+```python
+from asgard import GenericBotMessage, ToolCallConsentResponseItem, ToolCallConsentResult, PostBackAction
+
+# After receiving a tool_call.consent event:
+consent_items = [
+    ToolCallConsentResponseItem(
+        tool_call_id="tc-1",
+        result=ToolCallConsentResult.ALLOW_ONCE,
+    )
+]
+
+response = GenericBotMessage(
+    custom_channel_id="ch-1",
+    custom_message_id="m-2",
+    action=PostBackAction.RESPONSE_TOOL_CALL_CONSENT,
+    tool_call_consents=consent_items,
+)
+reply = client.send_message(response)
+```