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

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/.gitignore

@@ -5,3 +5,4 @@ __pycache__/
 dist/
 *.egg-info/
 .eggs/
+.env

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/PKG-INFO

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

persona_sdk_python-0.1.2/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.1 → persona_sdk_python-0.1.2}/persona_sdk/__init__.py

@@ -12,10 +12,11 @@ from persona_sdk.api.service_prices import ServicePricesApi
 
 
 class PersonaSdk:
-    def __init__(self, base_url: str, api_key: str, proxy: str = None):
+    def __init__(self, base_url: str, api_key: str, proxy: str = None, workflows_url: str = None):
         self.client = PersonaClient(base_url, api_key, proxy=proxy)
+        self.workflows_client = PersonaClient(workflows_url, api_key) if workflows_url else self.client
         self.agents = AgentsApi(self.client)
-        self.workflows = WorkflowsApi(self.client)
+        self.workflows = WorkflowsApi(self.workflows_client)
         self.triggers = TriggersApi(self.client)
         self.sessions = SessionsApi(self.client)
         self.credentials = CredentialsApi(self.client)
@@ -27,3 +28,5 @@ class PersonaSdk:
 
     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.1 → persona_sdk_python-0.1.2}/persona_sdk/api/agents.py

@@ -5,7 +5,7 @@ class AgentsApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/features.py

@@ -5,7 +5,7 @@ class FeaturesApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/knowledge_bases.py

@@ -5,7 +5,7 @@ class KnowledgeBasesApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword
@@ -23,7 +23,7 @@ class KnowledgeBasesApi:
     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 = 0, size: int = 20) -> dict:
+    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)
 

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/missions.py

@@ -5,7 +5,7 @@ class MissionsApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, status: str = None, page: int = 0, size: int = 20) -> dict:
+    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

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/projects.py

@@ -5,7 +5,7 @@ class ProjectsApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword
@@ -25,3 +25,18 @@ class ProjectsApi:
 
     async def delete(self, project_id: str) -> dict:
         return await self._client.delete(f"/projects/{project_id}")
+
+    async def get_subscription(self, project_id: str) -> dict:
+        return await self._client.get(f"/projects/{project_id}/subscription")
+
+    async def change_subscription_plan(self, project_id: str, to_plan_type: str) -> dict:
+        return await self._client.post(
+            f"/projects/{project_id}/subscription/actions/change-plan",
+            json={"toPlanType": to_plan_type},
+        )
+
+    async def add_subscription_credits(self, project_id: str, credits: int) -> dict:
+        return await self._client.post(
+            f"/projects/{project_id}/subscription/actions/add-credits",
+            json={"credits": credits},
+        )

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/service_prices.py

@@ -5,7 +5,7 @@ class ServicePricesApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/sessions.py

@@ -11,7 +11,7 @@ class SessionsApi:
         status: str = None,
         agent_id: str = None,
         user_id: str = None,
-        page: int = 0,
+        page: int = 1,
         size: int = 20,
     ) -> dict:
         params = {"page": page, "size": size}
@@ -34,7 +34,7 @@ class SessionsApi:
     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 = 0, size: int = 20) -> dict:
+    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)
 

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/triggers.py

@@ -5,7 +5,7 @@ class TriggersApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword
@@ -26,7 +26,7 @@ class TriggersApi:
     async def execute(self, trigger_id: str) -> dict:
         return await self._client.post(f"/triggers/{trigger_id}/executions")
 
-    async def list_executions(self, trigger_id: str, page: int = 0, size: int = 20) -> dict:
+    async def list_executions(self, trigger_id: str, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         return await self._client.get(f"/triggers/{trigger_id}/executions", params=params)
 

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/persona_sdk/api/workflows.py

@@ -5,7 +5,7 @@ class WorkflowsApi:
     def __init__(self, client: PersonaClient):
         self._client = client
 
-    async def list(self, keyword: str = None, page: int = 0, size: int = 20) -> dict:
+    async def list(self, keyword: str = None, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         if keyword:
             params["keyword"] = keyword
@@ -29,6 +29,6 @@ class WorkflowsApi:
     async def queue(self, workflow_id: str, data: dict = None) -> dict:
         return await self._client.post(f"/workflows/{workflow_id}/queue", json=data or {})
 
-    async def list_executions(self, workflow_id: str, page: int = 0, size: int = 20) -> dict:
+    async def list_executions(self, workflow_id: str, page: int = 1, size: int = 20) -> dict:
         params = {"page": page, "size": size}
         return await self._client.get(f"/workflows/{workflow_id}/executions", params=params)

{persona_sdk_python-0.1.1 → persona_sdk_python-0.1.2}/pyproject.toml

@@ -1,16 +1,13 @@
 [project]
 name = "persona-sdk-python"
-version = "0.1.1"
+version = "0.1.2"
 description = "Python SDK client for Persona AI platform"
 requires-python = ">=3.10"
 dependencies = [
-    "persona-models",
+    "persona-models>=0.1.0",
     "httpx>=0.27.0",
 ]
 
-[tool.uv.sources]
-persona-models = { path = "../persona-models" }
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"