persona-sdk-python 0.2.17__tar.gz → 0.2.19__tar.gz

{persona_sdk_python-0.2.17 → persona_sdk_python-0.2.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persona-sdk-python
-Version: 0.2.17
+Version: 0.2.19
 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
@@ -53,9 +53,10 @@ async def main():
         auth="prs_your_project_api_key",
     )
 
-    # List agents in your project
-    agents = await sdk.agents.list()
-    print(agents)
+    # List agents in your project -> Paginated[AgentConfiguration]
+    page = await sdk.agents.list()
+    for agent in page.items:
+        print(agent.id, agent.name, agent.model.model_name)
 
     await sdk.close()
 
@@ -150,22 +151,37 @@ finally:
 
 ## CRUD example
 
+Every API method is typed via the pydantic models re-exported from
+`persona-models` (e.g. `AgentConfiguration`, `Project`, `Mission`, ...). Write
+methods accept either a model instance or a plain dict; read methods always
+return the parsed model (or `Paginated[...]` for list endpoints).
+
 ```python
-# Create an agent
-agent = await sdk.agents.create({
-    "name": "my-agent",
-    "model": {"modelName": "gpt-4o"},
-})
+from persona_sdk import AgentConfiguration, ModelConfiguration
+
+# Create an agent from a typed model
+agent = await sdk.agents.create(
+    AgentConfiguration(
+        name="my-agent",
+        model=ModelConfiguration(model_name="gpt-4o"),
+    )
+)
 
-# Read
-fetched = await sdk.agents.get(agent["id"])
+# Read -> AgentConfiguration
+fetched = await sdk.agents.get(agent.id)
 
-# Update
-fetched["name"] = "renamed-agent"
-await sdk.agents.update(agent["id"], fetched)
+# Update (mutate the model and send it back)
+fetched.name = "renamed-agent"
+await sdk.agents.update(agent.id, fetched)
 
 # Delete
-await sdk.agents.delete(agent["id"])
+await sdk.agents.delete(agent.id)
+```
+
+A plain dict is still accepted for backwards compatibility:
+
+```python
+agent = await sdk.agents.create({"name": "my-agent", "model": {"modelName": "gpt-4o"}})
 ```
 
 ## AI System Instructions Generation
@@ -184,22 +200,21 @@ instructions = await sdk.agents.generate_system_instructions(
     session_id="my-session-id",
 )
 
-# Get the project's architect agent configuration
+# Get the project's architect agent configuration -> AgentConfiguration
 architect = await sdk.agents.get_architect()
 ```
 
 ## Pagination
 
-List endpoints accept `keyword`, `page`, and `size`:
+List endpoints return a `Paginated[<Model>]` with typed `.items`, `.total`,
+`.page` and `.size`:
 
 ```python
-result = await sdk.agents.list(keyword="bot", page=1, size=20)
-# {
-#   "items": [...],
-#   "total": 42,
-#   "page": 1,
-#   "size": 20
-# }
+page = await sdk.agents.list(keyword="bot", page=1, size=20)
+# page.items  -> list[AgentConfiguration]
+# page.total  -> 42
+# page.page   -> 1
+# page.size   -> 20
 ```
 
 ## Workflows

{persona_sdk_python-0.2.17 → persona_sdk_python-0.2.19}/README.md

@@ -29,9 +29,10 @@ async def main():
         auth="prs_your_project_api_key",
     )
 
-    # List agents in your project
-    agents = await sdk.agents.list()
-    print(agents)
+    # List agents in your project -> Paginated[AgentConfiguration]
+    page = await sdk.agents.list()
+    for agent in page.items:
+        print(agent.id, agent.name, agent.model.model_name)
 
     await sdk.close()
 
@@ -126,22 +127,37 @@ finally:
 
 ## CRUD example
 
+Every API method is typed via the pydantic models re-exported from
+`persona-models` (e.g. `AgentConfiguration`, `Project`, `Mission`, ...). Write
+methods accept either a model instance or a plain dict; read methods always
+return the parsed model (or `Paginated[...]` for list endpoints).
+
 ```python
-# Create an agent
-agent = await sdk.agents.create({
-    "name": "my-agent",
-    "model": {"modelName": "gpt-4o"},
-})
+from persona_sdk import AgentConfiguration, ModelConfiguration
+
+# Create an agent from a typed model
+agent = await sdk.agents.create(
+    AgentConfiguration(
+        name="my-agent",
+        model=ModelConfiguration(model_name="gpt-4o"),
+    )
+)
 
-# Read
-fetched = await sdk.agents.get(agent["id"])
+# Read -> AgentConfiguration
+fetched = await sdk.agents.get(agent.id)
 
-# Update
-fetched["name"] = "renamed-agent"
-await sdk.agents.update(agent["id"], fetched)
+# Update (mutate the model and send it back)
+fetched.name = "renamed-agent"
+await sdk.agents.update(agent.id, fetched)
 
 # Delete
-await sdk.agents.delete(agent["id"])
+await sdk.agents.delete(agent.id)
+```
+
+A plain dict is still accepted for backwards compatibility:
+
+```python
+agent = await sdk.agents.create({"name": "my-agent", "model": {"modelName": "gpt-4o"}})
 ```
 
 ## AI System Instructions Generation
@@ -160,22 +176,21 @@ instructions = await sdk.agents.generate_system_instructions(
     session_id="my-session-id",
 )
 
-# Get the project's architect agent configuration
+# Get the project's architect agent configuration -> AgentConfiguration
 architect = await sdk.agents.get_architect()
 ```
 
 ## Pagination
 
-List endpoints accept `keyword`, `page`, and `size`:
+List endpoints return a `Paginated[<Model>]` with typed `.items`, `.total`,
+`.page` and `.size`:
 
 ```python
-result = await sdk.agents.list(keyword="bot", page=1, size=20)
-# {
-#   "items": [...],
-#   "total": 42,
-#   "page": 1,
-#   "size": 20
-# }
+page = await sdk.agents.list(keyword="bot", page=1, size=20)
+# page.items  -> list[AgentConfiguration]
+# page.total  -> 42
+# page.page   -> 1
+# page.size   -> 20
 ```
 
 ## Workflows

persona_sdk_python-0.2.19/bitbucket-pipelines.yml

@@ -0,0 +1,18 @@
+image: python:3.12
+
+pipelines:
+  branches:
+    main:
+      - 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.17 → persona_sdk_python-0.2.19}/persona_sdk/__init__.py

@@ -11,6 +11,7 @@ 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.api.human_tasks import HumanTasksApi
 from persona_sdk.auth import (
     ApiKeyAuthenticationProvider,
     AuthenticationProvider,
@@ -18,6 +19,27 @@ from persona_sdk.auth import (
 )
 from persona_sdk.client import PersonaClient
 
+# Re-export the pydantic models returned/accepted by the typed API so users can
+# build requests and inspect responses without depending on ``persona-models``
+# directly. These are intentionally the same objects used internally.
+from persona_models.common import Paginated
+from persona_models.agents import AgentConfiguration, ModelConfiguration
+from persona_models.credentials import AuthorizeRequest, Credentials
+from persona_models.features import FeatureTemplate
+from persona_models.knowledge_bases import (
+    KnowledgeBase,
+    KnowledgeBaseDocument,
+    SearchChunksRequest,
+)
+from persona_models.known_models import KnownModel
+from persona_models.mcp import GenerationRequest
+from persona_models.missions import CreateMissionRequest, Mission
+from persona_models.projects import Project
+from persona_models.service_prices import ServicePrice, UsageCost
+from persona_models.sessions import GenerationResponse, Message, Session
+from persona_models.triggers import Trigger, TriggerExecutionResult
+from persona_models.workflows import Workflow
+
 __all__ = [
     "PersonaSdk",
     "PersonaClient",
@@ -35,6 +57,30 @@ __all__ = [
     "SessionsApi",
     "TriggersApi",
     "WorkflowsApi",
+    "HumanTasksApi",
+    # Domain models (re-exported from persona-models)
+    "Paginated",
+    "AgentConfiguration",
+    "ModelConfiguration",
+    "AuthorizeRequest",
+    "Credentials",
+    "FeatureTemplate",
+    "KnowledgeBase",
+    "KnowledgeBaseDocument",
+    "SearchChunksRequest",
+    "KnownModel",
+    "GenerationRequest",
+    "GenerationResponse",
+    "CreateMissionRequest",
+    "Mission",
+    "Project",
+    "ServicePrice",
+    "UsageCost",
+    "Message",
+    "Session",
+    "Trigger",
+    "TriggerExecutionResult",
+    "Workflow",
 ]
 
 
@@ -71,9 +117,9 @@ class PersonaSdk:
         self,
         base_url: str,
         auth: Union[str, AuthenticationProvider, None] = None,
-        proxy: str = None,
-        workflows_url: str = None,
-        api_key: str = None,
+        proxy: str | None = None,
+        workflows_url: str | None = None,
+        api_key: str | None = None,
     ):
         # Backwards compatibility: keep the legacy `api_key` keyword
         if auth is None:
@@ -87,6 +133,7 @@ class PersonaSdk:
         )
         self.agents = AgentsApi(self.client)
         self.workflows = WorkflowsApi(self.workflows_client)
+        self.human_tasks = HumanTasksApi(self.workflows_client)
         self.triggers = TriggersApi(self.client)
         self.sessions = SessionsApi(self.client)
         self.credentials = CredentialsApi(self.client)

persona_sdk_python-0.2.19/persona_sdk/_serde.py

@@ -0,0 +1,20 @@
+"""Internal (de)serialization helpers shared by the typed API classes."""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def dump_payload(model: BaseModel | dict[str, Any] | None) -> dict[str, Any] | None:
+    """Serialize a write payload for an HTTP request.
+
+    Accepts either a pydantic model instance (serialized to a camelCase dict,
+    dropping unset/``None`` fields so server-side defaults are preserved) or a
+    plain dict which is returned as-is. ``None`` passes through unchanged.
+    """
+    if model is None:
+        return None
+    if isinstance(model, BaseModel):
+        return model.model_dump(by_alias=True, exclude_none=True)
+    return dict(model)

persona_sdk_python-0.2.19/persona_sdk/api/agents.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Any
+
+from persona_models.agents import AgentConfiguration
+from persona_models.common import Paginated
+
+from persona_sdk._serde import dump_payload
+from persona_sdk.client import PersonaClient
+
+
+class AgentsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self,
+        keyword: str | None = None,
+        page: int = 1,
+        size: int = 20,
+    ) -> Paginated[AgentConfiguration]:
+        """List agents in the authenticated project."""
+        params: dict[str, Any] = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        data = await self._client.get("/agents", params=params)
+        return Paginated[AgentConfiguration].model_validate(data)
+
+    async def get(self, agent_id: str) -> AgentConfiguration:
+        return AgentConfiguration.model_validate(
+            await self._client.get(f"/agents/{agent_id}")
+        )
+
+    async def create(
+        self, agent: AgentConfiguration | dict[str, Any]
+    ) -> AgentConfiguration:
+        data = await self._client.post("/agents", json=dump_payload(agent))
+        return AgentConfiguration.model_validate(data)
+
+    async def update(
+        self,
+        agent_id: str,
+        agent: AgentConfiguration | dict[str, Any],
+    ) -> AgentConfiguration:
+        data = await self._client.put(f"/agents/{agent_id}", json=dump_payload(agent))
+        return AgentConfiguration.model_validate(data)
+
+    async def delete(self, agent_id: str) -> AgentConfiguration:
+        data = await self._client.delete(f"/agents/{agent_id}")
+        return AgentConfiguration.model_validate(data)
+
+    async def get_voices(self, synthesizer_type: str) -> dict[str, Any]:
+        """List available voices for a TTS synthesizer type."""
+        return await self._client.get(f"/values/synthesizers/{synthesizer_type}/voices")
+
+    async def generate_system_instructions(
+        self, prompt: str, session_id: str | None = None
+    ) -> str:
+        """Generate system instructions using the project's AI architect agent."""
+        body: dict[str, Any] = {"prompt": prompt}
+        if session_id:
+            body["sessionId"] = session_id
+        result = await self._client.post("/agents/system-instructions", json=body)
+        return result.get("instructions", "") if isinstance(result, dict) else ""
+
+    async def get_architect(self) -> AgentConfiguration:
+        """Get or create the project's architect agent configuration."""
+        return AgentConfiguration.model_validate(
+            await self._client.get("/agents/architect")
+        )

persona_sdk_python-0.2.19/persona_sdk/api/credentials.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+from persona_models.credentials import AuthorizeRequest, Credentials
+
+from persona_sdk._serde import dump_payload
+from persona_sdk.client import PersonaClient
+
+
+class CredentialsApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(self) -> list[Credentials]:
+        data = await self._client.get("/credentials")
+        return [Credentials.model_validate(item) for item in (data or [])]
+
+    async def list_by_provider(self, provider: str) -> list[Credentials]:
+        data = await self._client.get(f"/credentials/{provider}")
+        return [Credentials.model_validate(item) for item in (data or [])]
+
+    async def get(self, credentials_id: str) -> Credentials:
+        data = await self._client.get(f"/credentials/all/{credentials_id}")
+        return Credentials.model_validate(data)
+
+    async def authorize(
+        self, provider: str, request: AuthorizeRequest | dict[str, Any]
+    ) -> dict[str, Any]:
+        """Authorize credentials for a provider.
+
+        Returns the server's ``AuthorizeResponse`` (``credentials``, ``state``,
+        ``redirect_url``) as a plain dict.
+        """
+        return await self._client.post(
+            f"/credentials/{provider}/authorize", json=dump_payload(request)
+        )
+
+    async def delete(self, credentials_id: str) -> dict[str, Any]:
+        return await self._client.delete(f"/credentials/all/{credentials_id}")

persona_sdk_python-0.2.19/persona_sdk/api/features.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any
+
+from persona_models.common import Paginated
+from persona_models.features import FeatureTemplate, McpServerConfiguration
+
+from persona_sdk._serde import dump_payload
+from persona_sdk.client import PersonaClient
+
+
+class FeaturesApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self, keyword: str | None = None, page: int = 1, size: int = 20
+    ) -> Paginated[FeatureTemplate]:
+        params: dict[str, Any] = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        data = await self._client.get("/features/templates", params=params)
+        return Paginated[FeatureTemplate].model_validate(data)
+
+    async def get(self, template_id: str) -> FeatureTemplate:
+        data = await self._client.get(f"/features/templates/{template_id}")
+        return FeatureTemplate.model_validate(data)
+
+    async def create(
+        self, feature_template: FeatureTemplate | dict[str, Any]
+    ) -> FeatureTemplate:
+        data = await self._client.post(
+            "/features/templates", json=dump_payload(feature_template)
+        )
+        return FeatureTemplate.model_validate(data)
+
+    async def update(
+        self, template_id: str, feature_template: FeatureTemplate | dict[str, Any]
+    ) -> FeatureTemplate:
+        data = await self._client.put(
+            f"/features/templates/{template_id}", json=dump_payload(feature_template)
+        )
+        return FeatureTemplate.model_validate(data)
+
+    async def delete(self, template_id: str) -> FeatureTemplate:
+        data = await self._client.delete(f"/features/templates/{template_id}")
+        return FeatureTemplate.model_validate(data)
+
+    async def get_mcp_tools(
+        self,
+        mcp_config: McpServerConfiguration | dict[str, Any],
+        credentials_id: str | None = None,
+    ) -> dict[str, Any]:
+        """List the tools exposed by an MCP server.
+
+        Returns the server's ``McpToolsResponse`` (``tools`` and optional
+        ``error``) as a plain dict.
+        """
+        params = {"credentialsId": credentials_id} if credentials_id else None
+        return await self._client.post(
+            "/features/templates/mcp/available-tools",
+            json=dump_payload(mcp_config),
+            params=params,
+        )

persona_sdk_python-0.2.19/persona_sdk/api/human_tasks.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from persona_sdk.client import PersonaClient
+
+
+class HumanTasksApi:
+    """
+    Human-in-the-loop tasks. A task is created when a workflow step
+    suspends waiting for a human (a declared ``human`` node or an agent
+    escalation); responding to it resumes the run.
+
+    Lives on the workflows service (same client as ``WorkflowsApi``).
+    Tasks are returned as plain dicts — the contract is owned by the
+    workflows service and intentionally not constrained here.
+    """
+
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self,
+        status: str | None = "pending",
+        assignee: str | None = None,
+        workflow_id: str | None = None,
+        execution_id: str | None = None,
+        page: int = 1,
+        size: int = 50,
+    ) -> dict[str, Any]:
+        """The project's human-task inbox (``Paginated[HumanTask]`` shape)."""
+        params: dict[str, Any] = {"page": page, "size": size}
+        if status:
+            params["status"] = status
+        if assignee:
+            params["assignee"] = assignee
+        if workflow_id:
+            params["workflowId"] = workflow_id
+        if execution_id:
+            params["executionId"] = execution_id
+        return await self._client.get("/human-tasks", params=params)
+
+    async def respond(
+        self,
+        human_task_id: str,
+        response: Any,
+        responded_by: str | None = None,
+    ) -> dict[str, Any]:
+        """Answer a pending human task and resume the suspended execution."""
+        body: dict[str, Any] = {"response": response}
+        if responded_by:
+            body["respondedBy"] = responded_by
+        return await self._client.post(
+            f"/human-tasks/{human_task_id}/respond", json=body
+        )

persona_sdk_python-0.2.19/persona_sdk/api/knowledge_bases.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+from persona_models.common import Paginated
+from persona_models.knowledge_bases import (
+    KnowledgeBase,
+    KnowledgeBaseDocument,
+    SearchChunksRequest,
+)
+
+from persona_sdk._serde import dump_payload
+from persona_sdk.client import PersonaClient
+
+
+class KnowledgeBasesApi:
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self, keyword: str | None = None, page: int = 1, size: int = 20
+    ) -> Paginated[KnowledgeBase]:
+        params: dict[str, Any] = {"page": page, "size": size}
+        if keyword:
+            params["keyword"] = keyword
+        data = await self._client.get("/knowledges", params=params)
+        return Paginated[KnowledgeBase].model_validate(data)
+
+    async def get(self, knowledge_base_id: str) -> KnowledgeBase:
+        data = await self._client.get(f"/knowledges/{knowledge_base_id}")
+        return KnowledgeBase.model_validate(data)
+
+    async def create(
+        self, knowledge_base: KnowledgeBase | dict[str, Any]
+    ) -> KnowledgeBase:
+        data = await self._client.post("/knowledges", json=dump_payload(knowledge_base))
+        return KnowledgeBase.model_validate(data)
+
+    async def update(
+        self, knowledge_base_id: str, knowledge_base: KnowledgeBase | dict[str, Any]
+    ) -> KnowledgeBase:
+        data = await self._client.put(
+            f"/knowledges/{knowledge_base_id}", json=dump_payload(knowledge_base)
+        )
+        return KnowledgeBase.model_validate(data)
+
+    async def delete(self, knowledge_base_id: str) -> KnowledgeBase:
+        data = await self._client.delete(f"/knowledges/{knowledge_base_id}")
+        return KnowledgeBase.model_validate(data)
+
+    async def list_documents(
+        self, knowledge_base_id: str, page: int = 1, size: int = 20
+    ) -> Paginated[KnowledgeBaseDocument]:
+        params: dict[str, Any] = {"page": page, "size": size}
+        data = await self._client.get(
+            f"/knowledges/{knowledge_base_id}/documents", params=params
+        )
+        return Paginated[KnowledgeBaseDocument].model_validate(data)
+
+    async def delete_document(
+        self, knowledge_base_id: str, document_id: str
+    ) -> KnowledgeBaseDocument:
+        data = await self._client.delete(
+            f"/knowledges/{knowledge_base_id}/documents/{document_id}"
+        )
+        return KnowledgeBaseDocument.model_validate(data)
+
+    async def search_chunks(
+        self,
+        knowledge_base_id: str,
+        request: SearchChunksRequest | dict[str, Any],
+    ) -> list[dict[str, Any]]:
+        """Search a knowledge base for matching chunks.
+
+        Each chunk has the server-side ``ChunkResult`` shape
+        (``id``, ``text``, ``score``, ``metadata``, ``documentId``).
+        """
+        data = await self._client.post(
+            f"/knowledges/{knowledge_base_id}/search", json=dump_payload(request)
+        )
+        return list(data or [])