amigo_sdk 0.9.0__tar.gz → 0.11.0__tar.gz

{amigo_sdk-0.9.0 → amigo_sdk-0.11.0}/.github/workflows/auto-release.yml

@@ -30,7 +30,9 @@ jobs:
           echo "spec_url=$SPEC_URL" >> $GITHUB_OUTPUT
 
       - name: Fetch current production spec
-        run: curl -fSL -o openapi-new.json "${{ steps.spec.outputs.spec_url }}"
+        run: |
+          mkdir -p specs
+          curl -fSL -o specs/openapi-new.json "${{ steps.spec.outputs.spec_url }}"
 
       - name: Check baseline presence
         id: baseline
@@ -46,7 +48,7 @@ jobs:
         run: |
           mkdir -p specs
           if [ ! -f specs/openapi-baseline.json ]; then
-            cp openapi-new.json specs/openapi-baseline.json
+            cp specs/openapi-new.json specs/openapi-baseline.json
           fi
 
       - name: Diagnostics (spec and baseline)
@@ -71,7 +73,7 @@ jobs:
                 with_entries(.value |= sort_deep)
               else . end;
             (del(.info) | del(.servers)) | sort_deep
-          ' openapi-new.json > new.norm.json
+          ' specs/openapi-new.json > new.norm.json
           if [ -f baseline.norm.json ]; then
             echo "BASELINE_NORM_SHA=$(sha256sum baseline.norm.json | awk '{print $1}')"
           else
@@ -99,10 +101,10 @@ jobs:
             BASELINE_PATHS_COUNT=0
             BASELINE_SCHEMAS_COUNT=0
           fi
-          NEW_PATHS_SHA=$(jq -cS '(.paths // {})' openapi-new.json | sha256sum | awk '{print $1}')
-          NEW_SCHEMAS_SHA=$(jq -cS '(.components.schemas // {})' openapi-new.json | sha256sum | awk '{print $1}')
-          NEW_PATHS_COUNT=$(jq -r '(.paths // {}) | keys | length' openapi-new.json)
-          NEW_SCHEMAS_COUNT=$(jq -r '(.components.schemas // {}) | keys | length' openapi-new.json)
+          NEW_PATHS_SHA=$(jq -cS '(.paths // {})' specs/openapi-new.json | sha256sum | awk '{print $1}')
+          NEW_SCHEMAS_SHA=$(jq -cS '(.components.schemas // {})' specs/openapi-new.json | sha256sum | awk '{print $1}')
+          NEW_PATHS_COUNT=$(jq -r '(.paths // {}) | keys | length' specs/openapi-new.json)
+          NEW_SCHEMAS_COUNT=$(jq -r '(.components.schemas // {}) | keys | length' specs/openapi-new.json)
           echo "BASELINE paths: count=$BASELINE_PATHS_COUNT sha=$BASELINE_PATHS_SHA"
           echo "NEW      paths: count=$NEW_PATHS_COUNT sha=$NEW_PATHS_SHA"
           echo "BASELINE schemas: count=$BASELINE_SCHEMAS_COUNT sha=$BASELINE_SCHEMAS_SHA"
@@ -114,7 +116,7 @@ jobs:
           else
             : > baseline.paths.txt
           fi
-          jq -r '(.paths // {}) | keys | sort[]' openapi-new.json > new.paths.txt
+          jq -r '(.paths // {}) | keys | sort[]' specs/openapi-new.json > new.paths.txt
           echo "Removed paths (in baseline, not in new):"; comm -23 baseline.paths.txt new.paths.txt || true
           echo "Added paths (in new, not in baseline):"; comm -13 baseline.paths.txt new.paths.txt || true
 
@@ -124,7 +126,7 @@ jobs:
           else
             : > baseline.schemas.txt
           fi
-          jq -r '(.components.schemas // {}) | keys | sort[]' openapi-new.json > new.schemas.txt
+          jq -r '(.components.schemas // {}) | keys | sort[]' specs/openapi-new.json > new.schemas.txt
           echo "Removed schemas (in baseline, not in new):"; comm -23 baseline.schemas.txt new.schemas.txt || true
           echo "Added schemas (in new, not in baseline):"; comm -13 baseline.schemas.txt new.schemas.txt || true
 
@@ -152,7 +154,7 @@ jobs:
                 with_entries(.value |= sort_deep)
               else . end;
             (del(.info) | del(.servers)) | sort_deep
-          ' openapi-new.json > new.norm.json
+          ' specs/openapi-new.json > new.norm.json
           if diff -q baseline.norm.json new.norm.json >/dev/null 2>&1; then
             echo "changed=false" >> $GITHUB_OUTPUT
           else

{amigo_sdk-0.9.0 → amigo_sdk-0.11.0}/.github/workflows/release.yml

@@ -51,13 +51,20 @@ jobs:
     needs: test
 
     steps:
+      - name: Create GitHub App token (release-bot)
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.RELEASE_BOT_APP_ID }}
+          private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
+
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           # Fetch full history for version tagging
           fetch-depth: 0
           # Use a token that can push tags and create releases
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ steps.app-token.outputs.token }}
 
       - name: Ensure jq
         run: sudo apt-get update && sudo apt-get install -y jq
@@ -69,13 +76,11 @@ jobs:
           if [ -z "$SPEC_URL" ]; then
             SPEC_URL="https://api.amigo.ai/v1/openapi.json"
           fi
-          curl -fSL -o openapi-new.json "$SPEC_URL"
           mkdir -p specs
-          cp openapi-new.json specs/openapi-baseline.json
+          curl -fSL -o specs/openapi-new.json "$SPEC_URL"
+          cp specs/openapi-new.json specs/openapi-baseline.json
 
-      # Optional: if your generator can take a spec path
-      - name: Set spec path for generator
-        run: echo "OPENAPI_SPEC_PATH=$GITHUB_WORKSPACE/openapi-new.json" >> $GITHUB_ENV
+      # Generator always fetches remote; no local spec path needed
 
       - name: Setup Python
         uses: actions/setup-python@v5
@@ -152,7 +157,7 @@ jobs:
         if: ${{ !inputs.dry_run }}
         uses: actions/create-release@v1
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
         with:
           tag_name: "v${{ steps.new_version.outputs.version }}"
           release_name: "Release v${{ steps.new_version.outputs.version }}"

{amigo_sdk-0.9.0 → amigo_sdk-0.11.0}/.gitignore

@@ -12,4 +12,7 @@ dist/
 # Coverage files
 htmlcov/
 coverage.xml
-.coverage
+.coverage
+
+# CI/Temp OpenAPI spec (fetched during workflows)
+specs/openapi-new.json

amigo_sdk-0.11.0/CONTRIBUTING.md

@@ -0,0 +1,137 @@
+# Contributing Guide
+
+## Quick Setup
+
+```bash
+# Create and activate virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install the project in development mode
+pip install -e ".[dev]"
+```
+
+## Development Commands
+
+```bash
+check                     # Run all checks (format, lint, tests)
+check --fix               # Auto-fix issues and run all checks
+check --fast              # Format + lint only (skip tests)
+
+gen-models                # Generate models from API spec
+```
+
+## Workflow
+
+1. **Before committing:** Run `check --fix` to auto-fix issues
+2. **During development:** Use `check --fast` for quick validation
+3. **Update models:** Run `gen-models` when API changes
+
+## Release Process
+
+### GitHub Actions Release
+
+1. Go to the **Actions** tab in GitHub
+2. Select the **Release** workflow
+3. Click **Run workflow** and choose:
+   - **Version type**: `patch` (default), `minor`, or `major`
+   - **Dry run**: Test the release process without publishing
+
+The workflow will automatically:
+
+- ✅ Run all tests, linting, and formatting checks (reuses existing test workflow)
+- 🔄 Generate fresh models from the API spec
+- 📈 Increment the version using Hatch
+- 📦 Build the package
+- 🚀 Upload to PyPI
+- 🏷️ Create a Git tag and GitHub release
+- 📋 Provide detailed summary with links
+
+### Required Repository Secrets
+
+Configure these secrets in your GitHub repository settings:
+
+- `PYPI_API_TOKEN`: Token for https://pypi.org/ (production releases)
+- `CODECOV_TOKEN`: Token for Codecov uploads (used by CI test workflow)
+- `RELEASE_BOT_APP_ID`: GitHub App ID used to create tags/releases
+- `RELEASE_BOT_PRIVATE_KEY`: GitHub App private key (PEM) for the release bot
+
+### Getting API Tokens
+
+1. **PyPI**: Go to https://pypi.org/manage/account/token/
+2. Create a token with upload permissions
+3. Add the token to your repository secrets
+
+## Auto-Release (OpenAPI changes)
+
+When the backend OpenAPI spec changes, the SDK can auto-release a new version.
+
+- Trigger: a `repository_dispatch` event with type `openapi-updated`
+- Detect job: fetches the provided `spec_url` (or defaults to `https://api.amigo.ai/v1/openapi.json`), normalizes and compares against `specs/openapi-baseline.json`
+- If changed: invokes the release workflow with `version_type=minor` and passes `spec_url` (supports `dry_run`)
+- Release workflow: regenerates models, bumps version, builds, publishes to PyPI, pushes tag, and creates a GitHub release
+
+Manual trigger example (repository_dispatch):
+
+```bash
+curl -X POST \
+  -H "Accept: application/vnd.github+json" \
+  -H "Authorization: Bearer $GH_TOKEN" \
+  https://api.github.com/repos/<OWNER>/<REPO>/dispatches \
+  -d '{
+    "event_type": "openapi-updated",
+    "client_payload": {
+      "spec_url": "https://api.amigo.ai/v1/openapi.json",
+      "dry_run": true
+    }
+  }'
+```
+
+Notes:
+
+- The baseline file `specs/openapi-baseline.json` is created on first run and updated as part of the release workflow.
+- Ensure the secrets listed above are configured so the workflow can push tags, create releases, and publish to PyPI.
+
+### Manual trigger using GitHub CLI (gh)
+
+Requires `gh` authenticated with a token that can dispatch events on the SDK repos.
+
+```bash
+# Values that mirror the workflow
+OWNER="amigo-ai"
+BACKEND_REPO="$OWNER/backend"
+COMMIT_SHA="$(git rev-parse HEAD 2>/dev/null || echo manual-test)"
+RUN_ID="$(date +%s)"  # stand-in for GitHub Actions run_id
+
+for repo in amigo-typescript-sdk amigo-python-sdk; do
+  echo "Notifying $repo..."
+  gh api "repos/$OWNER/$repo/dispatches" \
+    --method POST \
+    --header 'Accept: application/vnd.github+json' \
+    --input - <<EOF || echo "⚠️  Failed to notify $repo"
+{
+  "event_type": "openapi-updated",
+  "client_payload": {
+    "spec_url": "https://api.amigo.ai/v1/openapi.json",
+    "commit_sha": "$COMMIT_SHA",
+    "backend_repo": "$BACKEND_REPO",
+    "backend_run_id": "$RUN_ID"
+  }
+}
+EOF
+done
+```
+
+## IDE Setup (VS Code)
+
+Install extensions:
+
+- [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+
+## Troubleshooting
+
+- **Command not found:** Activate virtual environment with `source .venv/bin/activate`
+- **Linting failures:** Run `check --fix` to auto-fix issues
+- **Model import errors:** Run `gen-models` to regenerate models
+- **Release failures:** Check API tokens are configured in repository secrets and try a dry run first

{amigo_sdk-0.9.0 → amigo_sdk-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amigo_sdk
-Version: 0.9.0
+Version: 0.11.0
 Summary: Amigo AI Python SDK
 Author: Amigo AI
 License-File: LICENSE
@@ -50,7 +50,7 @@ This SDK auto-generates its types from the latest [Amigo OpenAPI schema](https:/
 
 ```python
 from amigo_sdk import AmigoClient
-from amigo_sdk.generated.model import GetConversationsParametersQuery
+from amigo_sdk.models import GetConversationsParametersQuery
 
 # Initialize and use the client synchronously
 with AmigoClient(
@@ -65,9 +65,38 @@ with AmigoClient(
     print("Conversations:", conversations)
 ```
 
+## Quick Start (async)
+
+```python
+import asyncio
+
+from amigo_sdk import AsyncAmigoClient
+from amigo_sdk.models import GetConversationsParametersQuery
+
+
+async def main():
+    async with AsyncAmigoClient(
+        api_key="your-api-key",
+        api_key_id="your-api-key-id",
+        user_id="user-id",
+        organization_id="your-organization-id",
+    ) as client:
+        conversations = await client.conversation.get_conversations(
+            GetConversationsParametersQuery(limit=10, sort_by=["-created_at"])
+        )
+        print("Conversations:", conversations)
+
+
+asyncio.run(main())
+```
+
 ## Examples
 
-For more SDK usage examples see checkout the [examples/](examples/README.md) folder.
+For more SDK usage examples see the [examples overview](examples/README.md). Direct links:
+
+- **Conversation (sync)**: [examples/conversation/conversation.py](examples/conversation/conversation.py)
+- **Conversation (async)**: [examples/conversation/conversation_async.py](examples/conversation/conversation_async.py)
+- **User management (sync)**: [examples/user/user-management.py](examples/user/user-management.py)
 
 ## Configuration
 
@@ -133,6 +162,43 @@ The SDK provides access to the following resources:
 - **Conversation**: Manage conversations
 - **User**: Manage users
 
+## Generated types
+
+The SDK ships with Pydantic models generated from the latest OpenAPI schema.
+
+- **Importing types**: Import directly from `amigo_sdk.models`
+
+  ```python
+  from amigo_sdk.models import (
+      GetConversationsParametersQuery,
+      ConversationCreateConversationRequest,
+      GetUsersParametersQuery,
+  )
+  ```
+
+- **Using types when calling SDK functions**: Pass request/query models to resource methods.
+
+  ```python
+  from amigo_sdk import AmigoClient
+  from amigo_sdk.models import GetConversationsParametersQuery
+
+  with AmigoClient() as client:
+     conversations = client.conversation.get_conversations(
+         GetConversationsParametersQuery(limit=20, sort_by=["-created_at"])
+     )
+  ```
+
+- **Parsing returned objects**: Responses are Pydantic models. Access fields directly or convert to dict/JSON.
+
+  ```python
+  # Access fields
+  first = conversations.conversations[0]
+  print(first.id, first.created_at)
+
+  # Convert to plain dict for logging/serialization
+  print(first.model_dump(mode="json"))
+  ```
+
 ## Error Handling
 
 The SDK provides typed error handling:
@@ -162,6 +228,20 @@ except Exception as error:
     print("Unexpected error:", error)
 ```
 
+## Retries
+
+The HTTP client includes sensible, configurable retries:
+
+- **Defaults**:
+
+  - max attempts: 3
+  - backoff base: 0.25s (exponential with full jitter)
+  - max delay per attempt: 30s
+  - retry on status: {408, 429, 500, 502, 503, 504}
+  - retry on methods: {"GET"}
+  - special-case: POST is retried on 429 when `Retry-After` is present
+  - 401 triggers a one-time token refresh and immediate retry
+
 ## Development
 
 For detailed development setup, testing, and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

{amigo_sdk-0.9.0 → amigo_sdk-0.11.0}/README.md

@@ -28,7 +28,7 @@ This SDK auto-generates its types from the latest [Amigo OpenAPI schema](https:/
 
 ```python
 from amigo_sdk import AmigoClient
-from amigo_sdk.generated.model import GetConversationsParametersQuery
+from amigo_sdk.models import GetConversationsParametersQuery
 
 # Initialize and use the client synchronously
 with AmigoClient(
@@ -43,9 +43,38 @@ with AmigoClient(
     print("Conversations:", conversations)
 ```
 
+## Quick Start (async)
+
+```python
+import asyncio
+
+from amigo_sdk import AsyncAmigoClient
+from amigo_sdk.models import GetConversationsParametersQuery
+
+
+async def main():
+    async with AsyncAmigoClient(
+        api_key="your-api-key",
+        api_key_id="your-api-key-id",
+        user_id="user-id",
+        organization_id="your-organization-id",
+    ) as client:
+        conversations = await client.conversation.get_conversations(
+            GetConversationsParametersQuery(limit=10, sort_by=["-created_at"])
+        )
+        print("Conversations:", conversations)
+
+
+asyncio.run(main())
+```
+
 ## Examples
 
-For more SDK usage examples see checkout the [examples/](examples/README.md) folder.
+For more SDK usage examples see the [examples overview](examples/README.md). Direct links:
+
+- **Conversation (sync)**: [examples/conversation/conversation.py](examples/conversation/conversation.py)
+- **Conversation (async)**: [examples/conversation/conversation_async.py](examples/conversation/conversation_async.py)
+- **User management (sync)**: [examples/user/user-management.py](examples/user/user-management.py)
 
 ## Configuration
 
@@ -111,6 +140,43 @@ The SDK provides access to the following resources:
 - **Conversation**: Manage conversations
 - **User**: Manage users
 
+## Generated types
+
+The SDK ships with Pydantic models generated from the latest OpenAPI schema.
+
+- **Importing types**: Import directly from `amigo_sdk.models`
+
+  ```python
+  from amigo_sdk.models import (
+      GetConversationsParametersQuery,
+      ConversationCreateConversationRequest,
+      GetUsersParametersQuery,
+  )
+  ```
+
+- **Using types when calling SDK functions**: Pass request/query models to resource methods.
+
+  ```python
+  from amigo_sdk import AmigoClient
+  from amigo_sdk.models import GetConversationsParametersQuery
+
+  with AmigoClient() as client:
+     conversations = client.conversation.get_conversations(
+         GetConversationsParametersQuery(limit=20, sort_by=["-created_at"])
+     )
+  ```
+
+- **Parsing returned objects**: Responses are Pydantic models. Access fields directly or convert to dict/JSON.
+
+  ```python
+  # Access fields
+  first = conversations.conversations[0]
+  print(first.id, first.created_at)
+
+  # Convert to plain dict for logging/serialization
+  print(first.model_dump(mode="json"))
+  ```
+
 ## Error Handling
 
 The SDK provides typed error handling:
@@ -140,6 +206,20 @@ except Exception as error:
     print("Unexpected error:", error)
 ```
 
+## Retries
+
+The HTTP client includes sensible, configurable retries:
+
+- **Defaults**:
+
+  - max attempts: 3
+  - backoff base: 0.25s (exponential with full jitter)
+  - max delay per attempt: 30s
+  - retry on status: {408, 429, 500, 502, 503, 504}
+  - retry on methods: {"GET"}
+  - special-case: POST is retried on 429 when `Retry-After` is present
+  - 401 triggers a one-time token refresh and immediate retry
+
 ## Development
 
 For detailed development setup, testing, and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).