persona-sdk-python 0.1.2__tar.gz → 0.2.4__tar.gz

persona_sdk_python-0.2.4/DEPLOY.md

@@ -0,0 +1,112 @@
+# Deploy to PyPI
+
+Operational guide for publishing `persona-sdk-python` to PyPI.
+
+Reference: same strategy used by `applica-iam-client`.
+
+---
+
+## Prerequisites
+
+### 1. PyPI account
+
+- Go to https://pypi.org/account/register/
+- If the account already exists (e.g. the one used for `applica-iam-client`), skip this step
+
+### 2. PyPI API Token
+
+1. Login at https://pypi.org
+2. Go to **Account Settings** → **API tokens**
+3. Click **Add API token**
+   - Name: `persona-sdk-python-deploy`
+   - Scope: **Entire account** (for the first release, you can restrict to the project later)
+4. Copy the token (starts with `pypi-...`) — it is shown only once
+
+### 3. Configure the token on Bitbucket
+
+1. Go to the Bitbucket repository for `persona-sdk-python`
+2. **Repository settings** → **Pipelines** → **Repository variables**
+3. Add:
+   - **Name:** `PYPI_TOKEN`
+   - **Value:** the copied token (e.g. `pypi-AgEIcH...`)
+   - **Secured:** checked
+
+---
+
+## Automated Release (Bitbucket Pipelines)
+
+Every push to `main` automatically publishes a new version.
+
+The version is computed as `0.1.{BITBUCKET_BUILD_NUMBER}`, so it auto-increments
+(e.g. build #1 → `0.1.1`, build #14 → `0.1.14`, build #203 → `0.1.203`).
+
+When you want a major/minor bump, change the prefix in `bitbucket-pipelines.yml`
+(e.g. from `0.1.` to `0.2.` or `1.0.`).
+
+### Flow:
+
+```
+git push origin main
+       │
+       ▼
+Pipeline triggers
+       │
+       ▼
+Updates version in pyproject.toml (0.1.$BUILD_NUMBER)
+       │
+       ▼
+Build (sdist + wheel)
+       │
+       ▼
+Upload to PyPI via twine with $PYPI_TOKEN
+       │
+       ▼
+Creates git tag (0.1.$BUILD_NUMBER) and pushes it
+```
+
+---
+
+## Manual Release (from local machine)
+
+If you want to publish without the pipeline, from your terminal:
+
+```bash
+cd /path/to/persona-sdk-python
+
+# 1. Update the version in pyproject.toml
+# Edit the line: version = "0.1.X"
+
+# 2. Build
+pip install build
+python -m build
+
+# 3. Upload
+pip install twine
+twine upload dist/* -u __token__ -p pypi-YOUR_TOKEN_HERE
+
+# 4. Tag
+git tag -a 0.1.X -m "0.1.X"
+git push origin 0.1.X
+```
+
+---
+
+## Verification
+
+After release, verify that the package is available:
+
+```bash
+pip install persona-sdk-python --upgrade
+```
+
+Or check at: https://pypi.org/project/persona-sdk-python/
+
+---
+
+## First Release — Checklist
+
+- [ ] PyPI account created/existing
+- [ ] API Token generated on PyPI
+- [ ] Token configured as `PYPI_TOKEN` in Bitbucket repository variables
+- [ ] Push to `main` → pipeline runs → package published
+- [ ] `pip install persona-sdk-python` works

persona_sdk_python-0.2.4/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: persona-sdk-python
+Version: 0.2.4
+Summary: Async Python SDK for the Persona AI platform
+Project-URL: Homepage, https://persona.applica.guru
+Project-URL: Repository, https://bitbucket.org/applicaguru/persona-sdk-python
+Author: Applica Software Guru
+License: Proprietary
+Keywords: agents,ai,async,persona,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: persona-models>=0.1.0
+Description-Content-Type: text/markdown
+
+# persona-sdk-python
+
+Async Python SDK for the [Persona AI](https://persona.applica.guru) platform.
+
+## Installation
+
+```bash
+pip install persona-sdk-python
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add persona-sdk-python
+```
+
+Requirements: Python 3.10+
+
+## Quick start
+
+```python
+import asyncio
+from persona_sdk import PersonaSdk
+
+
+async def main():
+    sdk = PersonaSdk(
+        base_url="https://persona.applica.guru/api",
+        auth="prs_your_project_api_key",
+    )
+
+    # List agents in your project
+    agents = await sdk.agents.list()
+    print(agents)
+
+    await sdk.close()
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The SDK supports two authentication methods via the `auth` parameter.
+
+### API key (default)
+
+A plain string is wrapped automatically in `ApiKeyAuthenticationProvider` and
+sent as the `x-persona-apikey` header. Accepts:
+
+- Master key (full admin access)
+- Project API key (`prs_...`)
+- Agent API key (`prs_ag_...`)
+
+```python
+from persona_sdk import PersonaSdk
+
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_your_project_api_key",
+)
+```
+
+### IAM Bearer token
+
+For applications that authenticate users via IAM, pass a
+`BearerTokenAuthenticationProvider` with a valid JWT:
+
+```python
+from persona_sdk import PersonaSdk, BearerTokenAuthenticationProvider
+
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth=BearerTokenAuthenticationProvider(iam_jwt_token),
+)
+```
+
+The token is sent as the `Authorization: Bearer <token>` header. The server
+validates it via the IAM service and resolves the user's project automatically.
+
+### Custom provider
+
+Implement your own provider by subclassing `AuthenticationProvider`:
+
+```python
+from persona_sdk import AuthenticationProvider
+
+class MyProvider(AuthenticationProvider):
+    def headers(self) -> dict[str, str]:
+        return {"x-custom-header": "value"}
+
+    def credentials(self) -> str:
+        return "my-credentials"
+```
+
+## Available APIs
+
+The `PersonaSdk` instance exposes one client per resource:
+
+| Attribute | Description |
+|-----------|-------------|
+| `sdk.agents` | Agent management (CRUD, voices) |
+| `sdk.projects` | Project management and subscriptions |
+| `sdk.sessions` | Sessions, messages, usage |
+| `sdk.knowledge_bases` | Knowledge bases, documents, chunk search |
+| `sdk.workflows` | Workflows, executions, queues |
+| `sdk.triggers` | Triggers and trigger executions |
+| `sdk.missions` | Missions (generate, execute, stop, continue) |
+| `sdk.features` | Feature templates and MCP tools |
+| `sdk.credentials` | OAuth credentials and authorization |
+| `sdk.service_prices` | Service pricing |
+
+Each API method is fully async. Always close the SDK when done:
+
+```python
+sdk = PersonaSdk(...)
+try:
+    agents = await sdk.agents.list()
+finally:
+    await sdk.close()
+```
+
+Or use it as an async context manager pattern:
+
+```python
+sdk = PersonaSdk(...)
+async with sdk.client._client:  # internal httpx client
+    ...
+```
+
+## CRUD example
+
+```python
+# Create an agent
+agent = await sdk.agents.create({
+    "name": "my-agent",
+    "model": {"modelName": "gpt-4o"},
+})
+
+# Read
+fetched = await sdk.agents.get(agent["id"])
+
+# Update
+fetched["name"] = "renamed-agent"
+await sdk.agents.update(agent["id"], fetched)
+
+# Delete
+await sdk.agents.delete(agent["id"])
+```
+
+## Pagination
+
+List endpoints accept `keyword`, `page`, and `size`:
+
+```python
+result = await sdk.agents.list(keyword="bot", page=1, size=20)
+# {
+#   "items": [...],
+#   "total": 42,
+#   "page": 1,
+#   "size": 20
+# }
+```
+
+## Workflows
+
+If your workflows service runs on a different host, pass `workflows_url`:
+
+```python
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_...",
+    workflows_url="https://persona.applica.guru/workflows",
+)
+
+# Execute a workflow
+result = await sdk.workflows.execute(
+    workflow_id="wf-123",
+    data={"input": "value"},
+)
+```
+
+## Runners
+
+For higher-level abstractions, the SDK provides runners:
+
+```python
+from persona_sdk import PersonaClient
+from persona_sdk.runners import AgentRunner, invoke_tool, retrieve_resource
+
+client = PersonaClient(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_...",
+)
+
+# Run an agent in an existing session
+runner = AgentRunner(client=client, agent_id="agent-1", session_code="sess-1")
+response = await runner.run("Hello, agent!")
+
+# Invoke an MCP tool directly
+result = await invoke_tool(
+    client=client,
+    mcp_server_name="my-mcp",
+    transport=...,
+    tool_name="search",
+    args={"query": "hello"},
+)
+```
+
+## Proxy support
+
+```python
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_...",
+    proxy="http://proxy.local:8080",
+)
+```
+
+## License
+
+Proprietary — © Applica Software Guru

persona_sdk_python-0.2.4/README.md

@@ -0,0 +1,222 @@
+# persona-sdk-python
+
+Async Python SDK for the [Persona AI](https://persona.applica.guru) platform.
+
+## Installation
+
+```bash
+pip install persona-sdk-python
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add persona-sdk-python
+```
+
+Requirements: Python 3.10+
+
+## Quick start
+
+```python
+import asyncio
+from persona_sdk import PersonaSdk
+
+
+async def main():
+    sdk = PersonaSdk(
+        base_url="https://persona.applica.guru/api",
+        auth="prs_your_project_api_key",
+    )
+
+    # List agents in your project
+    agents = await sdk.agents.list()
+    print(agents)
+
+    await sdk.close()
+
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The SDK supports two authentication methods via the `auth` parameter.
+
+### API key (default)
+
+A plain string is wrapped automatically in `ApiKeyAuthenticationProvider` and
+sent as the `x-persona-apikey` header. Accepts:
+
+- Master key (full admin access)
+- Project API key (`prs_...`)
+- Agent API key (`prs_ag_...`)
+
+```python
+from persona_sdk import PersonaSdk
+
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_your_project_api_key",
+)
+```
+
+### IAM Bearer token
+
+For applications that authenticate users via IAM, pass a
+`BearerTokenAuthenticationProvider` with a valid JWT:
+
+```python
+from persona_sdk import PersonaSdk, BearerTokenAuthenticationProvider
+
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth=BearerTokenAuthenticationProvider(iam_jwt_token),
+)
+```
+
+The token is sent as the `Authorization: Bearer <token>` header. The server
+validates it via the IAM service and resolves the user's project automatically.
+
+### Custom provider
+
+Implement your own provider by subclassing `AuthenticationProvider`:
+
+```python
+from persona_sdk import AuthenticationProvider
+
+class MyProvider(AuthenticationProvider):
+    def headers(self) -> dict[str, str]:
+        return {"x-custom-header": "value"}
+
+    def credentials(self) -> str:
+        return "my-credentials"
+```
+
+## Available APIs
+
+The `PersonaSdk` instance exposes one client per resource:
+
+| Attribute | Description |
+|-----------|-------------|
+| `sdk.agents` | Agent management (CRUD, voices) |
+| `sdk.projects` | Project management and subscriptions |
+| `sdk.sessions` | Sessions, messages, usage |
+| `sdk.knowledge_bases` | Knowledge bases, documents, chunk search |
+| `sdk.workflows` | Workflows, executions, queues |
+| `sdk.triggers` | Triggers and trigger executions |
+| `sdk.missions` | Missions (generate, execute, stop, continue) |
+| `sdk.features` | Feature templates and MCP tools |
+| `sdk.credentials` | OAuth credentials and authorization |
+| `sdk.service_prices` | Service pricing |
+
+Each API method is fully async. Always close the SDK when done:
+
+```python
+sdk = PersonaSdk(...)
+try:
+    agents = await sdk.agents.list()
+finally:
+    await sdk.close()
+```
+
+Or use it as an async context manager pattern:
+
+```python
+sdk = PersonaSdk(...)
+async with sdk.client._client:  # internal httpx client
+    ...
+```
+
+## CRUD example
+
+```python
+# Create an agent
+agent = await sdk.agents.create({
+    "name": "my-agent",
+    "model": {"modelName": "gpt-4o"},
+})
+
+# Read
+fetched = await sdk.agents.get(agent["id"])
+
+# Update
+fetched["name"] = "renamed-agent"
+await sdk.agents.update(agent["id"], fetched)
+
+# Delete
+await sdk.agents.delete(agent["id"])
+```
+
+## Pagination
+
+List endpoints accept `keyword`, `page`, and `size`:
+
+```python
+result = await sdk.agents.list(keyword="bot", page=1, size=20)
+# {
+#   "items": [...],
+#   "total": 42,
+#   "page": 1,
+#   "size": 20
+# }
+```
+
+## Workflows
+
+If your workflows service runs on a different host, pass `workflows_url`:
+
+```python
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_...",
+    workflows_url="https://persona.applica.guru/workflows",
+)
+
+# Execute a workflow
+result = await sdk.workflows.execute(
+    workflow_id="wf-123",
+    data={"input": "value"},
+)
+```
+
+## Runners
+
+For higher-level abstractions, the SDK provides runners:
+
+```python
+from persona_sdk import PersonaClient
+from persona_sdk.runners import AgentRunner, invoke_tool, retrieve_resource
+
+client = PersonaClient(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_...",
+)
+
+# Run an agent in an existing session
+runner = AgentRunner(client=client, agent_id="agent-1", session_code="sess-1")
+response = await runner.run("Hello, agent!")
+
+# Invoke an MCP tool directly
+result = await invoke_tool(
+    client=client,
+    mcp_server_name="my-mcp",
+    transport=...,
+    tool_name="search",
+    args={"query": "hello"},
+)
+```
+
+## Proxy support
+
+```python
+sdk = PersonaSdk(
+    base_url="https://persona.applica.guru/api",
+    auth="prs_...",
+    proxy="http://proxy.local:8080",
+)
+```
+
+## License
+
+Proprietary — © Applica Software Guru

persona_sdk_python-0.2.4/bitbucket-pipelines.yml

@@ -0,0 +1,17 @@
+image: python:3.12
+
+pipelines:
+  default:
+    - step:
+        name: Publish to PyPI
+        caches:
+          - pip
+        script:
+          - apt-get update && apt-get install -y git
+          - pip install build twine
+          - export VERSION=0.2.$BITBUCKET_BUILD_NUMBER
+          - sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          - python -m build
+          - twine upload dist/* -u __token__ -p $PYPI_TOKEN
+          - git tag -a $VERSION -m "$VERSION"
+          - git push origin $VERSION

persona_sdk_python-0.2.4/persona_sdk/__init__.py

@@ -0,0 +1,100 @@
+from typing import Union
+
+from persona_sdk.api.agents import AgentsApi
+from persona_sdk.api.credentials import CredentialsApi
+from persona_sdk.api.features import FeaturesApi
+from persona_sdk.api.knowledge_bases import KnowledgeBasesApi
+from persona_sdk.api.missions import MissionsApi
+from persona_sdk.api.projects import ProjectsApi
+from persona_sdk.api.service_prices import ServicePricesApi
+from persona_sdk.api.sessions import SessionsApi
+from persona_sdk.api.triggers import TriggersApi
+from persona_sdk.api.workflows import WorkflowsApi
+from persona_sdk.auth import (
+    ApiKeyAuthenticationProvider,
+    AuthenticationProvider,
+    BearerTokenAuthenticationProvider,
+)
+from persona_sdk.client import PersonaClient
+
+__all__ = [
+    "PersonaSdk",
+    "PersonaClient",
+    "AuthenticationProvider",
+    "ApiKeyAuthenticationProvider",
+    "BearerTokenAuthenticationProvider",
+    "AgentsApi",
+    "CredentialsApi",
+    "FeaturesApi",
+    "KnowledgeBasesApi",
+    "MissionsApi",
+    "ProjectsApi",
+    "ServicePricesApi",
+    "SessionsApi",
+    "TriggersApi",
+    "WorkflowsApi",
+]
+
+
+class PersonaSdk:
+    """
+    Persona SDK facade.
+
+    Args:
+        base_url: Base URL of persona-core (e.g. https://persona.applica.guru/api).
+        auth: An ``AuthenticationProvider`` (preferred) or a plain string with
+            the API key / JWT token. Strings are wrapped in
+            ``ApiKeyAuthenticationProvider`` for backwards compatibility.
+        proxy: Optional HTTP proxy URL.
+        workflows_url: Optional separate base URL for the workflows service.
+            If provided, a second client is created using the same auth.
+        api_key: Deprecated keyword-only alias for ``auth``. Provided for
+            backwards compatibility with previous SDK versions.
+
+    Examples:
+        Using an API key (legacy)::
+
+            sdk = PersonaSdk("http://localhost:8000", "prs_my_key")
+
+        Using an IAM Bearer token::
+
+            from persona_sdk import BearerTokenAuthenticationProvider
+            sdk = PersonaSdk(
+                "http://localhost:8000",
+                BearerTokenAuthenticationProvider(jwt_token),
+            )
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth: Union[str, AuthenticationProvider, None] = None,
+        proxy: str = None,
+        workflows_url: str = None,
+        api_key: str = None,
+    ):
+        # Backwards compatibility: keep the legacy `api_key` keyword
+        if auth is None:
+            if api_key is None:
+                raise ValueError("Either 'auth' or 'api_key' must be provided")
+            auth = api_key
+
+        self.client = PersonaClient(base_url, auth, proxy=proxy)
+        self.workflows_client = (
+            PersonaClient(workflows_url, auth) if workflows_url else self.client
+        )
+        self.agents = AgentsApi(self.client)
+        self.workflows = WorkflowsApi(self.workflows_client)
+        self.triggers = TriggersApi(self.client)
+        self.sessions = SessionsApi(self.client)
+        self.credentials = CredentialsApi(self.client)
+        self.knowledge_bases = KnowledgeBasesApi(self.client)
+        self.projects = ProjectsApi(self.client)
+        self.features = FeaturesApi(self.client)
+        self.missions = MissionsApi(self.client)
+        self.service_prices = ServicePricesApi(self.client)
+
+    async def close(self):
+        await self.client.close()
+        if self.workflows_client is not self.client:
+            await self.workflows_client.close()

persona_sdk_python-0.2.4/persona_sdk/auth/__init__.py

@@ -0,0 +1,11 @@
+"""Authentication providers for the Persona SDK."""
+
+from persona_sdk.auth.api_key_auth import ApiKeyAuthenticationProvider
+from persona_sdk.auth.base import AuthenticationProvider
+from persona_sdk.auth.bearer_token_auth import BearerTokenAuthenticationProvider
+
+__all__ = [
+    "AuthenticationProvider",
+    "ApiKeyAuthenticationProvider",
+    "BearerTokenAuthenticationProvider",
+]