Metadata-Version: 2.4
Name: persona-sdk-python
Version: 0.2.13
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.2.2
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, AI instructions, architect) |
| `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 to release the
underlying HTTP connection pool:

```python
sdk = PersonaSdk(
    base_url="https://persona.applica.guru/api",
    auth="prs_your_api_key",
)
try:
    agents = await sdk.agents.list()
finally:
    await sdk.close()
```

## 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"])
```

## AI System Instructions Generation

Generate system instructions for an agent using the project's AI architect:

```python
# Generate from a description
instructions = await sdk.agents.generate_system_instructions(
    "Create a customer support agent that handles billing inquiries"
)

# Multi-turn refinement with session ID
instructions = await sdk.agents.generate_system_instructions(
    "Add a rule to always ask for the order number first",
    session_id="my-session-id",
)

# Get the project's architect agent configuration
architect = await sdk.agents.get_architect()
```

## 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
