persona-sdk-python 0.1.0__tar.gz

persona_sdk_python-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.eggs/

persona_sdk_python-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: persona-sdk-python
+Version: 0.1.0
+Summary: Python SDK client for Persona AI platform
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: persona-models>=0.1.0

persona_sdk_python-0.1.0/README.md

@@ -0,0 +1,351 @@
+# Persona Python SDK
+
+Python SDK client for the Persona AI platform.
+
+## Installation & Setup
+
+```python
+# Requirements: Python >= 3.10, httpx>=0.27.0, persona-models
+from persona_sdk import PersonaSdk
+
+sdk = PersonaSdk(
+    base_url="http://localhost:8000",
+    api_key="<api-key-or-jwt-token>",
+    workflows_url="http://...",  # optional, defaults to base_url
+)
+
+# Always close the client when done
+await sdk.close()
+```
+
+All methods are **async**. The SDK exposes: `sdk.agents`, `sdk.sessions`, `sdk.workflows`, `sdk.knowledge_bases`, `sdk.triggers`, `sdk.credentials`, `sdk.projects`, `sdk.features`, `sdk.missions`, `sdk.service_prices`.
+
+---
+
+## Sending Messages to an Agent — `AgentRunner`
+
+```python
+from persona_sdk.runners import AgentRunner
+
+async with AgentRunner(
+    client=sdk.client,
+    agent_id="my-agent",
+    session_code="session-123",    # optional, auto-generated if omitted
+    parent_session_id=None,        # optional
+    user_id="user-456",            # optional
+    session_type="async",          # "async" | "realtime"
+) as runner:
+
+    # Plain string
+    response = await runner.run("Hello!")
+
+    # Structured Message object
+    from persona_models.sessions import Message
+    response = await runner.run(Message(role="user", text="Hello!"))
+
+    # List of messages
+    response = await runner.run([Message(...), Message(...)])
+
+    # Force structured JSON output (Pydantic schema)
+    from pydantic import BaseModel
+    class MyOutput(BaseModel):
+        answer: str
+    response = await runner.run("Tell me something", response_schema=MyOutput)
+
+    # With initial context (data + optional files)
+    from persona_models.sessions import AgentContext
+    response = await runner.run("Hello!", context=AgentContext(data={"user_name": "Alice"}))
+```
+
+### `AgentResponse`
+
+```python
+response.text                  # str — concatenated text from all messages
+response.messages              # List[Message]
+response.is_json()             # bool
+response.to_json()             # dict | list | None
+response.function_calls        # List[FunctionCall]
+response.first_function_call   # FunctionCall | None
+response.is_transfer()         # bool — True if agent delegated to another agent
+```
+
+### `Message` fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `str` | auto-generated UUID |
+| `role` | `"user"`, `"assistant"`, `"function"`, `"tool"` | |
+| `text` | `str \| None` | |
+| `image` | `Image \| None` | base64-encoded |
+| `file` | `File \| None` | name, url or base64, content_type |
+| `function_calls` | `List[FunctionCall] \| None` | |
+| `function_response` | `FunctionResponse \| None` | |
+| `finish_reason` | `"stop"`, `"function_call"`, `None` | |
+| `thought` | `bool` | True for reasoning/thought messages |
+| `sources` | `list \| None` | RAG sources |
+
+---
+
+## Agent Schema — `AgentConfiguration`
+
+Used when creating or updating agents via `sdk.agents.create(agent.model_dump(by_alias=True))`.
+
+```python
+from persona_models.agents import (
+    AgentConfiguration, ModelConfiguration, SynthesizerConfiguration,
+    TranscriberConfiguration, ToolkitConfiguration, Tool, ToolRemoteConfig,
+    KnowledgeConfiguration, CollaborationConfiguration,
+    WakeupConfiguration, TelegramConfiguration, WhatsAppConfiguration,
+    StmConfiguration, Variable, Collaborator,
+)
+
+agent = AgentConfiguration(
+    name="MyAgent",
+    description="An assistant agent",
+    model=ModelConfiguration(
+        model_name="gemini-2.0-flash",  # see supported models below
+        temperature=1.0,
+        reasoning_effort=None,          # "minimal"|"low"|"medium"|"high"|None
+    ),
+    system_instructions="You are a helpful assistant.",
+    language_code="en-US",             # "en-US"|"it-IT"|"es-ES"|"fr-FR"|"de-DE"|"pt-BR"
+    initial_message="Hello! How can I help?",
+    enabled_protocols=["rest", "websocket"],  # "webrtc"|"twilio"|"rest"|"websocket"|"telegram"
+    variables=[Variable(name="company", value="Acme", description="Company name")],
+
+    # Voice synthesis (optional)
+    synthesizer=SynthesizerConfiguration(
+        enabled=True,
+        synthesizer_name="gcloud",     # "gcloud"|"elevenlabs"|"gtts"|"openai"
+        language_code="en-US",
+        voice="en-US-Neural2-A",
+        sample_rate_hertz=24000,
+    ),
+
+    # Speech transcription (optional)
+    transcriber=TranscriberConfiguration(
+        enabled=True,
+        transcriber_name="gcloud",     # "gcloud"|"deepgram"
+        language_code="en-US",
+    ),
+
+    # Tools (optional)
+    toolkit=ToolkitConfiguration(tools=[
+        Tool(
+            type="remote",             # "remote"|"local"
+            name="my_tool",
+            description="Does something",
+            config=ToolRemoteConfig(service_url="https://...", secret="s3cr3t", timeout=60),
+        )
+    ]),
+
+    # Knowledge base / RAG (optional)
+    knowledge=KnowledgeConfiguration(
+        enabled=True,
+        knowledge_type="simple",       # "simple"|"multi_hop"
+        knowledge_base_id="kb-id",
+        namespace="my-namespace",
+        number_of_entries=3,
+    ),
+
+    # Multi-agent collaboration (optional)
+    collaboration=CollaborationConfiguration(
+        enabled=True,
+        mode="delegate_and_return",    # "persistent_transfer"|"delegate_and_return"|"consult_then_respond"
+        max_number_of_iterations=10,
+        collaborators=[Collaborator(agent_id="other-agent-id", scope="handle billing questions")],
+    ),
+
+    # Short-term memory (optional)
+    short_term_memory=StmConfiguration(
+        type="summary",                # "simple"|"summary"
+        max_messages=10,
+        max_number_of_words=50,
+        include_tool_calls=False,
+    ),
+
+    verbose_errors=False,
+)
+
+result = await sdk.agents.create(agent.model_dump(by_alias=True))
+```
+
+### Supported `model_name` values
+
+| Provider | Models |
+|---|---|
+| Google | `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash`, … |
+| OpenAI | `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`, `o4-mini`, `o3-mini`, `o1`, `o1-mini`, … |
+| Grok | `grok-4-0709`, `grok-3`, `grok-3-mini`, `grok-2-vision-1212`, … |
+| Fireworks | `accounts/fireworks/models/deepseek-v3p2`, `accounts/fireworks/models/kimi-k2p5`, … |
+| Other | `ollama` (requires `url` and `ollama_model_name` in `ModelConfiguration`) |
+
+---
+
+## Agents API
+
+```python
+agents = await sdk.agents.list(keyword="chatbot", page=1, size=20)
+agent  = await sdk.agents.get("agent-id")
+agent  = await sdk.agents.create({...})            # AgentConfiguration.model_dump(by_alias=True)
+agent  = await sdk.agents.update("agent-id", {...})
+        await sdk.agents.delete("agent-id")
+voices = await sdk.agents.get_voices("elevenlabs") # "gcloud"|"elevenlabs"|"gtts"|"openai"
+```
+
+---
+
+## Sessions API
+
+```python
+sessions = await sdk.sessions.list(keyword=None, status=None, agent_id=None, user_id=None, page=1, size=20)
+session  = await sdk.sessions.get("session-id")
+usage    = await sdk.sessions.get_usage("session-id")
+messages = await sdk.sessions.get_messages("session-code", page=1, size=20)
+result   = await sdk.sessions.generate_message("session-code", request_dict)
+          await sdk.sessions.delete("session-code")
+```
+
+---
+
+## Workflows API
+
+### `Workflow` schema
+
+```python
+from persona_models.workflows import Workflow, Node, Connection
+
+workflow = Workflow(
+    name="My Workflow",
+    description="Does something useful",
+    nodes=[
+        Node(id="node-1", type="agent", label="Step 1", data={"agentId": "agent-id"}),
+        Node(id="node-2", type="agent", label="Step 2", data={"agentId": "agent-id-2"}),
+    ],
+    connections=[
+        Connection(source_id="node-1", target_id="node-2"),
+    ],
+    root_node=Node(id="node-0", type="trigger", label="Start"),
+)
+```
+
+```python
+workflows = await sdk.workflows.list(keyword=None, page=1, size=20)
+wf        = await sdk.workflows.get("wf-id")
+wf        = await sdk.workflows.create(workflow.model_dump(by_alias=True))
+wf        = await sdk.workflows.update("wf-id", {...})
+           await sdk.workflows.delete("wf-id")
+
+# Synchronous execution — waits for result
+result    = await sdk.workflows.execute("wf-id", data={"input": "value"})
+
+# Async execution — enqueues, returns immediately
+result    = await sdk.workflows.queue("wf-id", data={"input": "value"})
+
+# Past executions
+execs     = await sdk.workflows.list_executions("wf-id", page=1, size=20)
+```
+
+---
+
+## Knowledge Bases API
+
+### `KnowledgeBase` schema
+
+```python
+from persona_models.knowledge_bases import KnowledgeBase
+
+kb = KnowledgeBase(
+    name="My KB",
+    description="Product documentation",
+    quality="high",           # "extremely_high"|"very_high"|"high"|"medium"|"low"
+    chunk_size="medium",      # "small"|"medium"|"large"
+    embedding_model="text-multilingual-embedding-002",
+)
+```
+
+```python
+kbs     = await sdk.knowledge_bases.list()
+kb      = await sdk.knowledge_bases.get("kb-id")
+kb      = await sdk.knowledge_bases.create(kb.model_dump(by_alias=True))
+kb      = await sdk.knowledge_bases.update("kb-id", {...})
+         await sdk.knowledge_bases.delete("kb-id")
+
+docs    = await sdk.knowledge_bases.list_documents("kb-id", page=1, size=20)
+         await sdk.knowledge_bases.delete_document("kb-id", "doc-id")
+
+# Semantic search
+results = await sdk.knowledge_bases.search_chunks("kb-id", {
+    "query": "search text",
+    "topK": 5,
+    "threshold": 0.7,   # optional, float 0-1
+})
+```
+
+---
+
+## MCP Tools — `ToolInvoker`
+
+```python
+from persona_sdk.runners import ToolInvoker
+from persona_models.mcp import McpTransport
+
+result = await ToolInvoker.invoke(
+    client=sdk.client,
+    mcp_server_name="my-mcp-server",
+    transport=McpTransport(...),
+    tool_name="my_tool",
+    args={"param1": "value1"},
+    session_id="session-123",     # optional
+    user_id="user-456",           # optional
+    billing_disabled=False,
+)
+# returns ToolInvokeResponse
+```
+
+## MCP Resources — `ResourceRetriever`
+
+```python
+from persona_sdk.runners import ResourceRetriever
+
+content = await ResourceRetriever.retrieve(
+    client=sdk.client,
+    mcp_server_name="my-mcp-server",
+    transport=McpTransport(...),
+    uri="resource://...",
+    session_id="session-123",
+)
+# returns: str (text), dict {"content": ..., "content_type": ...} (blob), or None
+```
+
+---
+
+## Complete Example
+
+```python
+import asyncio
+from persona_sdk import PersonaSdk
+from persona_sdk.runners import AgentRunner
+from persona_models.agents import AgentConfiguration, ModelConfiguration
+
+async def main():
+    sdk = PersonaSdk(base_url="http://localhost:8000", api_key="my-key")
+    try:
+        # Create an agent
+        agent = AgentConfiguration(
+            name="Assistant",
+            model=ModelConfiguration(model_name="gemini-2.0-flash"),
+            system_instructions="You are a helpful assistant.",
+        )
+        created = await sdk.agents.create(agent.model_dump(by_alias=True))
+        agent_id = created["id"]
+
+        # Run a conversation
+        async with AgentRunner(sdk.client, agent_id=agent_id) as runner:
+            response = await runner.run("What is the capital of France?")
+            print(response.text)
+    finally:
+        await sdk.close()
+
+asyncio.run(main())
+```

persona_sdk_python-0.1.0/persona_sdk/__init__.py

@@ -0,0 +1,32 @@
+from persona_sdk.client import PersonaClient
+from persona_sdk.api.agents import AgentsApi
+from persona_sdk.api.workflows import WorkflowsApi
+from persona_sdk.api.triggers import TriggersApi
+from persona_sdk.api.sessions import SessionsApi
+from persona_sdk.api.credentials import CredentialsApi
+from persona_sdk.api.knowledge_bases import KnowledgeBasesApi
+from persona_sdk.api.projects import ProjectsApi
+from persona_sdk.api.features import FeaturesApi
+from persona_sdk.api.missions import MissionsApi
+from persona_sdk.api.service_prices import ServicePricesApi
+
+
+class PersonaSdk:
+    def __init__(self, base_url: str, api_key: str, workflows_url: str = None):
+        self.client = PersonaClient(base_url, api_key)
+        self.workflows_client = PersonaClient(workflows_url, api_key) 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.1.0/persona_sdk/api/agents.py

@@ -0,0 +1,27 @@
+from persona_sdk.client import PersonaClient
+
+
+class AgentsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        return await self._client.get("/agents", params=params)
+
+    async def get(self, agent_id: str) -> dict:
+        return await self._client.get(f"/agents/{agent_id}")
+
+    async def create(self, agent: dict) -> dict:
+        return await self._client.post("/agents", json=agent)
+
+    async def update(self, agent_id: str, agent: dict) -> dict:
+        return await self._client.put(f"/agents/{agent_id}", json=agent)
+
+    async def delete(self, agent_id: str) -> dict:
+        return await self._client.delete(f"/agents/{agent_id}")
+
+    async def get_voices(self, synthesizer_type: str) -> dict:
+        return await self._client.get(f"/values/synthesizers/{synthesizer_type}/voices")

persona_sdk_python-0.1.0/persona_sdk/api/credentials.py

@@ -0,0 +1,21 @@
+from persona_sdk.client import PersonaClient
+
+
+class CredentialsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self) -> dict:
+        return await self._client.get("/credentials")
+
+    async def list_by_provider(self, provider: str) -> dict:
+        return await self._client.get(f"/credentials/{provider}")
+
+    async def get(self, credentials_id: str) -> dict:
+        return await self._client.get(f"/credentials/all/{credentials_id}")
+
+    async def authorize(self, provider: str, request: dict) -> dict:
+        return await self._client.post(f"/credentials/{provider}/authorize", json=request)
+
+    async def delete(self, credentials_id: str) -> dict:
+        return await self._client.delete(f"/credentials/all/{credentials_id}")

persona_sdk_python-0.1.0/persona_sdk/api/features.py

@@ -0,0 +1,27 @@
+from persona_sdk.client import PersonaClient
+
+
+class FeaturesApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        return await self._client.get("/features/templates", params=params)
+
+    async def get(self, template_id: str) -> dict:
+        return await self._client.get(f"/features/templates/{template_id}")
+
+    async def create(self, feature_template: dict) -> dict:
+        return await self._client.post("/features/templates", json=feature_template)
+
+    async def update(self, template_id: str, feature_template: dict) -> dict:
+        return await self._client.put(f"/features/templates/{template_id}", json=feature_template)
+
+    async def delete(self, template_id: str) -> dict:
+        return await self._client.delete(f"/features/templates/{template_id}")
+
+    async def get_mcp_tools(self, mcp_config: dict) -> dict:
+        return await self._client.post("/features/templates/mcp/available-tools", json=mcp_config)

persona_sdk_python-0.1.0/persona_sdk/api/knowledge_bases.py

@@ -0,0 +1,34 @@
+from persona_sdk.client import PersonaClient
+
+
+class KnowledgeBasesApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        return await self._client.get("/knowledges", params=params)
+
+    async def get(self, knowledge_base_id: str) -> dict:
+        return await self._client.get(f"/knowledges/{knowledge_base_id}")
+
+    async def create(self, knowledge_base: dict) -> dict:
+        return await self._client.post("/knowledges", json=knowledge_base)
+
+    async def update(self, knowledge_base_id: str, knowledge_base: dict) -> dict:
+        return await self._client.put(f"/knowledges/{knowledge_base_id}", json=knowledge_base)
+
+    async def delete(self, knowledge_base_id: str) -> dict:
+        return await self._client.delete(f"/knowledges/{knowledge_base_id}")
+
+    async def list_documents(self, knowledge_base_id: str, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        return await self._client.get(f"/knowledges/{knowledge_base_id}/documents", params=params)
+
+    async def delete_document(self, knowledge_base_id: str, document_id: str) -> dict:
+        return await self._client.delete(f"/knowledges/{knowledge_base_id}/documents/{document_id}")
+
+    async def search_chunks(self, knowledge_base_id: str, request: dict) -> dict:
+        return await self._client.post(f"/knowledges/{knowledge_base_id}/search", json=request)

persona_sdk_python-0.1.0/persona_sdk/api/missions.py

@@ -0,0 +1,41 @@
+from persona_sdk.client import PersonaClient
+
+
+class MissionsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self, keyword: str = None, status: str = None, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        if status:
+            params["status"] = status
+        return await self._client.get("/missions", params=params)
+
+    async def get(self, mission_id: str) -> dict:
+        return await self._client.get(f"/missions/{mission_id}")
+
+    async def create(self, mission: dict) -> dict:
+        return await self._client.post("/missions", json=mission)
+
+    async def update(self, mission_id: str, mission: dict) -> dict:
+        return await self._client.put(f"/missions/{mission_id}", json=mission)
+
+    async def delete(self, mission_id: str) -> dict:
+        return await self._client.delete(f"/missions/{mission_id}")
+
+    async def generate(self, mission_id: str) -> dict:
+        return await self._client.post(f"/missions/{mission_id}/generate")
+
+    async def execute(self, mission_id: str) -> dict:
+        return await self._client.post(f"/missions/{mission_id}/execute")
+
+    async def continue_mission(self, mission_id: str) -> dict:
+        return await self._client.post(f"/missions/{mission_id}/continue")
+
+    async def stop(self, mission_id: str) -> dict:
+        return await self._client.post(f"/missions/{mission_id}/stop")
+
+    async def send_instructions(self, mission_id: str, instructions: dict) -> dict:
+        return await self._client.post(f"/missions/{mission_id}/instructions", json=instructions)

persona_sdk_python-0.1.0/persona_sdk/api/projects.py

@@ -0,0 +1,27 @@
+from persona_sdk.client import PersonaClient
+
+
+class ProjectsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        return await self._client.get("/projects", params=params)
+
+    async def get(self, project_id: str) -> dict:
+        return await self._client.get(f"/projects/{project_id}")
+
+    async def get_mine(self) -> dict:
+        return await self._client.get("/projects/mine")
+
+    async def create(self, project: dict) -> dict:
+        return await self._client.post("/projects", json=project)
+
+    async def update(self, project_id: str, project: dict) -> dict:
+        return await self._client.put(f"/projects/{project_id}", json=project)
+
+    async def delete(self, project_id: str) -> dict:
+        return await self._client.delete(f"/projects/{project_id}")

persona_sdk_python-0.1.0/persona_sdk/api/service_prices.py

@@ -0,0 +1,24 @@
+from persona_sdk.client import PersonaClient
+
+
+class ServicePricesApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        return await self._client.get("/service-prices", params=params)
+
+    async def get(self, service_price_id: str) -> dict:
+        return await self._client.get(f"/service-prices/{service_price_id}")
+
+    async def create(self, service_price: dict) -> dict:
+        return await self._client.post("/service-prices", json=service_price)
+
+    async def update(self, service_price_id: str, service_price: dict) -> dict:
+        return await self._client.put(f"/service-prices/{service_price_id}", json=service_price)
+
+    async def delete(self, service_price_id: str) -> dict:
+        return await self._client.delete(f"/service-prices/{service_price_id}")

persona_sdk_python-0.1.0/persona_sdk/api/sessions.py

@@ -0,0 +1,42 @@
+from persona_sdk.client import PersonaClient
+
+
+class SessionsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self,
+        keyword: str = None,
+        status: str = None,
+        agent_id: str = None,
+        user_id: str = None,
+        page: int = 1,
+        size: int = 20,
+    ) -> dict:
+        params = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        if status:
+            params["status"] = status
+        if agent_id:
+            params["agentId"] = agent_id
+        if user_id:
+            params["userId"] = user_id
+        return await self._client.get("/sessions", params=params)
+
+    async def get(self, session_id: str) -> dict:
+        return await self._client.get(f"/sessions/{session_id}")
+
+    async def get_usage(self, session_id: str) -> dict:
+        return await self._client.get(f"/sessions/{session_id}/usage")
+
+    async def generate_message(self, code: str, request: dict) -> dict:
+        return await self._client.post(f"/sessions/{code}/messages", json=request)
+
+    async def get_messages(self, code: str, page: int = 1, size: int = 20) -> dict:
+        params = {"page": page, "size": size}
+        return await self._client.get(f"/sessions/{code}/messages", params=params)
+
+    async def delete(self, code: str) -> dict:
+        return await self._client.delete(f"/sessions/{code}")