persona-sdk-python 0.2.25__tar.gz → 0.2.26__tar.gz

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/.github/workflows/ci.yml

@@ -1,7 +1,7 @@
 name: CI
 
-# Smoke su PR: il repo non ha suite di test (non ne aveva in Bitbucket).
-# Lo smoke verifica che uv.lock risolva (--frozen) e che il package importi.
+# Smoke + test su PR: verifica che uv.lock risolva (--frozen), che il package importi
+# e che i test passino (httpx MockTransport: niente rete, niente server).
 # Il publish avviene solo al push su main (deploy.yml).
 
 on:
@@ -23,7 +23,8 @@ jobs:
           python-version: '3.12'
       - name: Installa uv
         run: pip install uv
-      - name: Smoke import
+      - name: Smoke import + test
         run: |
           uv sync --frozen
           uv run python -c "import persona_sdk; print('smoke ok:', persona_sdk.__name__)"
+          uv run pytest -q

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/.github/workflows/deploy.yml

@@ -64,7 +64,7 @@ jobs:
           echo "Versione finale: ${VERSION}"
 
   test:
-    name: Test (smoke import)
+    name: Test (smoke import + pytest)
     runs-on: ubuntu-latest
     if: github.event_name == 'push' || inputs.mode == 'test-and-publish'
     steps:
@@ -74,12 +74,13 @@ jobs:
           python-version: '3.12'
       - name: Installa uv
         run: pip install uv
-      - name: Smoke import
-        # il repo non ha suite di test (non ne aveva in Bitbucket): lo smoke
-        # verifica che uv.lock risolva e che il package importi
+      - name: Smoke import + test
+        # lo smoke verifica che uv.lock risolva e che il package importi;
+        # pytest esegue i test (httpx MockTransport: niente rete, niente server)
         run: |
           uv sync --frozen
           uv run python -c "import persona_sdk; print('smoke ok:', persona_sdk.__name__)"
+          uv run pytest -q
 
   build-package:
     name: Build & check sdist/wheel

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: persona-sdk-python
-Version: 0.2.25
+Version: 0.2.26
 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
@@ -19,7 +19,7 @@ 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.16
+Requires-Dist: persona-models>=0.2.20
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -140,6 +140,8 @@ The `PersonaSdk` instance exposes one client per resource:
 | `sdk.features` | Feature templates and MCP tools |
 | `sdk.credentials` | OAuth credentials and authorization |
 | `sdk.service_prices` | Service pricing |
+| `sdk.model_aliases` | Model aliases (`alias:<name>` -> concrete model), impact, health check, suggestions |
+| `sdk.notifications` | In-platform notifications (badge, read state) |
 
 Each API method is fully async. Always close the SDK when done to release the
 underlying HTTP connection pool:
@@ -223,6 +225,85 @@ page = await sdk.agents.list(keyword="bot", page=1, size=20)
 # page.size   -> 20
 ```
 
+## Model aliases
+
+A model alias is a named indirection: agents set their model to `alias:<name>` and
+the alias holds the concrete `provider/model`, ordered fallbacks and optional
+defaults, so changing one alias moves every agent that uses it. Writing needs a
+super admin, a project admin or the project API key.
+
+```python
+from persona_sdk import ModelAlias, ModelAliasDefaults, alias_ref
+
+# Create: only name, target, projectId, description, fallbacks and defaults are
+# sent (health, history and timestamps are managed by the server). A plain dict
+# with the same keys works too.
+alias = await sdk.model_aliases.create(
+    ModelAlias(
+        name="smart-default",
+        target="openai/gpt-5",
+        fallbacks=["anthropic/claude-sonnet-4"],
+        defaults=ModelAliasDefaults(max_output_tokens=4000),
+    )
+)
+
+# Point an agent at it
+agent.model.model_name = alias_ref("smart-default")  # "alias:smart-default"
+
+page = await sdk.model_aliases.list(keyword="smart", page=1, size=20)
+alias = await sdk.model_aliases.get(alias.id)
+
+# Move every agent to another model (name and scope are immutable)
+alias.target = "grok/grok-4"
+alias = await sdk.model_aliases.update(alias.id, alias)
+
+impact = await sdk.model_aliases.impact(alias.id)  # AliasImpact: total, usages
+alias = await sdk.model_aliases.check(alias.id)    # runs the health check now
+print(alias.health.status, alias.health.issues)
+```
+
+### Suggestions
+
+Replacement and fallback candidates for the alias' target (or for another model,
+e.g. a fallback that went missing). A proposal only: nothing is applied.
+
+```python
+sugg = await sdk.model_aliases.suggestions(alias.id, model="grok/grok-4", limit=5)
+for s in sugg.replacements:
+    print(s.model, s.context_window, s.warnings)
+```
+
+### Deleting an alias that is in use
+
+Deleting an alias still referenced by agents is refused with a `409`. The SDK
+raises the usual `httpx.HTTPStatusError`; `ModelAliasesApi.in_use` reads the
+blocking agents from it, or returns `None` for any other error:
+
+```python
+import httpx
+from persona_sdk import ModelAliasesApi
+
+try:
+    await sdk.model_aliases.remove(alias.id)
+except httpx.HTTPStatusError as e:
+    impact = ModelAliasesApi.in_use(e)
+    if impact is None:
+        raise
+    print(f"used by {impact.total} agent(s):", [u.agent_id for u in impact.usages])
+```
+
+## Notifications
+
+In-platform notifications (e.g. an alias whose model is being retired). A project
+sees its own; platform-wide ones are for super admins.
+
+```python
+page = await sdk.notifications.list(unread_only=True, page=1, size=20)
+badge = await sdk.notifications.unread_count()          # int
+n = await sdk.notifications.mark_read(page.items[0].id)  # -> Notification
+await sdk.notifications.mark_all_read(project_id="p1")   # returns None
+```
+
 ## Workflows
 
 If your workflows service runs on a different host, pass `workflows_url`:

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/README.md

@@ -116,6 +116,8 @@ The `PersonaSdk` instance exposes one client per resource:
 | `sdk.features` | Feature templates and MCP tools |
 | `sdk.credentials` | OAuth credentials and authorization |
 | `sdk.service_prices` | Service pricing |
+| `sdk.model_aliases` | Model aliases (`alias:<name>` -> concrete model), impact, health check, suggestions |
+| `sdk.notifications` | In-platform notifications (badge, read state) |
 
 Each API method is fully async. Always close the SDK when done to release the
 underlying HTTP connection pool:
@@ -199,6 +201,85 @@ page = await sdk.agents.list(keyword="bot", page=1, size=20)
 # page.size   -> 20
 ```
 
+## Model aliases
+
+A model alias is a named indirection: agents set their model to `alias:<name>` and
+the alias holds the concrete `provider/model`, ordered fallbacks and optional
+defaults, so changing one alias moves every agent that uses it. Writing needs a
+super admin, a project admin or the project API key.
+
+```python
+from persona_sdk import ModelAlias, ModelAliasDefaults, alias_ref
+
+# Create: only name, target, projectId, description, fallbacks and defaults are
+# sent (health, history and timestamps are managed by the server). A plain dict
+# with the same keys works too.
+alias = await sdk.model_aliases.create(
+    ModelAlias(
+        name="smart-default",
+        target="openai/gpt-5",
+        fallbacks=["anthropic/claude-sonnet-4"],
+        defaults=ModelAliasDefaults(max_output_tokens=4000),
+    )
+)
+
+# Point an agent at it
+agent.model.model_name = alias_ref("smart-default")  # "alias:smart-default"
+
+page = await sdk.model_aliases.list(keyword="smart", page=1, size=20)
+alias = await sdk.model_aliases.get(alias.id)
+
+# Move every agent to another model (name and scope are immutable)
+alias.target = "grok/grok-4"
+alias = await sdk.model_aliases.update(alias.id, alias)
+
+impact = await sdk.model_aliases.impact(alias.id)  # AliasImpact: total, usages
+alias = await sdk.model_aliases.check(alias.id)    # runs the health check now
+print(alias.health.status, alias.health.issues)
+```
+
+### Suggestions
+
+Replacement and fallback candidates for the alias' target (or for another model,
+e.g. a fallback that went missing). A proposal only: nothing is applied.
+
+```python
+sugg = await sdk.model_aliases.suggestions(alias.id, model="grok/grok-4", limit=5)
+for s in sugg.replacements:
+    print(s.model, s.context_window, s.warnings)
+```
+
+### Deleting an alias that is in use
+
+Deleting an alias still referenced by agents is refused with a `409`. The SDK
+raises the usual `httpx.HTTPStatusError`; `ModelAliasesApi.in_use` reads the
+blocking agents from it, or returns `None` for any other error:
+
+```python
+import httpx
+from persona_sdk import ModelAliasesApi
+
+try:
+    await sdk.model_aliases.remove(alias.id)
+except httpx.HTTPStatusError as e:
+    impact = ModelAliasesApi.in_use(e)
+    if impact is None:
+        raise
+    print(f"used by {impact.total} agent(s):", [u.agent_id for u in impact.usages])
+```
+
+## Notifications
+
+In-platform notifications (e.g. an alias whose model is being retired). A project
+sees its own; platform-wide ones are for super admins.
+
+```python
+page = await sdk.notifications.list(unread_only=True, page=1, size=20)
+badge = await sdk.notifications.unread_count()          # int
+n = await sdk.notifications.mark_read(page.items[0].id)  # -> Notification
+await sdk.notifications.mark_all_read(project_id="p1")   # returns None
+```
+
 ## Workflows
 
 If your workflows service runs on a different host, pass `workflows_url`:

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/persona_sdk/__init__.py

@@ -6,6 +6,8 @@ from persona_sdk.api.features import FeaturesApi
 from persona_sdk.api.knowledge_bases import KnowledgeBasesApi
 from persona_sdk.api.markup_rules import MarkupRulesApi
 from persona_sdk.api.missions import MissionsApi
+from persona_sdk.api.model_aliases import ModelAliasesApi
+from persona_sdk.api.notifications import NotificationsApi
 from persona_sdk.api.projects import ProjectsApi
 from persona_sdk.api.providers import ProvidersApi
 from persona_sdk.api.service_prices import ServicePricesApi
@@ -36,6 +38,16 @@ from persona_models.knowledge_bases import (
 from persona_models.markup import MarkupRule
 from persona_models.mcp import GenerationRequest
 from persona_models.missions import CreateMissionRequest, Mission
+from persona_models.model_aliases import (
+    AliasImpact,
+    AliasSuggestions,
+    ModelAlias,
+    ModelAliasDefaults,
+    alias_name_from_ref,
+    alias_ref,
+    is_alias_ref,
+)
+from persona_models.notifications import Notification
 from persona_models.projects import Project
 from persona_models.providers import Provider, ProviderModel
 from persona_models.service_prices import ServicePrice, UsageCost
@@ -55,6 +67,8 @@ __all__ = [
     "KnowledgeBasesApi",
     "MarkupRulesApi",
     "MissionsApi",
+    "ModelAliasesApi",
+    "NotificationsApi",
     "ProjectsApi",
     "ProvidersApi",
     "ServicePricesApi",
@@ -77,6 +91,14 @@ __all__ = [
     "GenerationResponse",
     "CreateMissionRequest",
     "Mission",
+    "ModelAlias",
+    "ModelAliasDefaults",
+    "AliasImpact",
+    "AliasSuggestions",
+    "Notification",
+    "alias_ref",
+    "is_alias_ref",
+    "alias_name_from_ref",
     "Project",
     "Provider",
     "ProviderModel",
@@ -152,6 +174,8 @@ class PersonaSdk:
         self.service_prices = ServicePricesApi(self.client)
         self.providers = ProvidersApi(self.client)
         self.markup_rules = MarkupRulesApi(self.client)
+        self.model_aliases = ModelAliasesApi(self.client)
+        self.notifications = NotificationsApi(self.client)
 
     async def close(self):
         await self.client.close()

persona_sdk_python-0.2.26/persona_sdk/api/model_aliases.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from persona_models.common import Paginated
+from persona_models.model_aliases import AliasImpact, AliasSuggestions, ModelAlias
+
+from persona_sdk.client import PersonaClient
+
+# The only fields a client controls. Health, history and timestamps are managed by
+# the server and persona-core rejects ``createdAt: null`` / ``updatedAt: null``.
+_INPUT_FIELDS = {
+    "name": "name",
+    "target": "target",
+    "project_id": "projectId",
+    "projectId": "projectId",
+    "description": "description",
+    "fallbacks": "fallbacks",
+    "defaults": "defaults",
+}
+
+
+def _alias_payload(alias: ModelAlias | dict[str, Any]) -> dict[str, Any]:
+    """Build the write body: user-controlled fields only, camelCase, no ``None``."""
+    if isinstance(alias, ModelAlias):
+        data = alias.model_dump(by_alias=True, exclude_none=True)
+        return {k: data[k] for k in set(_INPUT_FIELDS.values()) if k in data}
+    payload: dict[str, Any] = {}
+    for key, value in alias.items():
+        field = _INPUT_FIELDS.get(key)
+        if field is None or value is None:
+            continue
+        if field == "defaults" and hasattr(value, "model_dump"):
+            value = value.model_dump(by_alias=True, exclude_none=True)
+        elif field == "defaults":
+            value = {k: v for k, v in value.items() if v is not None}
+        payload[field] = value
+    return payload
+
+
+class ModelAliasesApi:
+    """Model aliases: a named indirection ``alias:<name>`` to a concrete
+    ``provider/model``, with ordered fallbacks and optional defaults. Writing needs
+    a super admin, a project admin or the project API key."""
+
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self,
+        project_id: str | None = None,
+        keyword: str | None = None,
+        page: int = 1,
+        size: int = 100,
+    ) -> Paginated[ModelAlias]:
+        """Aliases visible to the caller (their project's and the global ones)."""
+        params: dict[str, Any] = {"page": page, "size": size}
+        if project_id:
+            params["projectId"] = project_id
+        if keyword:
+            params["keyword"] = keyword
+        data = await self._client.get("/model-aliases", params=params)
+        return Paginated[ModelAlias].model_validate(data)
+
+    async def get(self, alias_id: str) -> ModelAlias:
+        data = await self._client.get(f"/model-aliases/{alias_id}")
+        return ModelAlias.model_validate(data)
+
+    async def create(self, alias: ModelAlias | dict[str, Any]) -> ModelAlias:
+        """Create an alias. Only name, target, projectId, description, fallbacks and
+        defaults are sent; server-managed fields are never sent."""
+        data = await self._client.post("/model-aliases", json=_alias_payload(alias))
+        return ModelAlias.model_validate(data)
+
+    async def update(
+        self, alias_id: str, alias: ModelAlias | dict[str, Any]
+    ) -> ModelAlias:
+        """Change target, fallbacks, defaults and description (``name`` and scope
+        are immutable)."""
+        data = await self._client.put(
+            f"/model-aliases/{alias_id}", json=_alias_payload(alias)
+        )
+        return ModelAlias.model_validate(data)
+
+    async def remove(self, alias_id: str) -> None:
+        """Delete an alias. Refused with a 409 while agents still reference it: use
+        ``ModelAliasesApi.in_use`` on the raised error to read which ones."""
+        await self._client.delete(f"/model-aliases/{alias_id}")
+
+    async def impact(self, alias_id: str) -> AliasImpact:
+        """Agents that reference the alias, and in which model slot."""
+        data = await self._client.get(f"/model-aliases/{alias_id}/impact")
+        return AliasImpact.model_validate(data)
+
+    async def check(self, alias_id: str) -> ModelAlias:
+        """Run the health check now; stores the result in ``health``."""
+        data = await self._client.post(f"/model-aliases/{alias_id}/check")
+        return ModelAlias.model_validate(data)
+
+    async def suggestions(
+        self, alias_id: str, model: str | None = None, limit: int | None = None
+    ) -> AliasSuggestions:
+        """Replacement and fallback candidates for the alias' target, or for
+        ``model``. A proposal only: nothing is applied."""
+        params: dict[str, Any] = {}
+        if model:
+            params["model"] = model
+        if limit is not None:
+            params["limit"] = limit
+        data = await self._client.get(
+            f"/model-aliases/{alias_id}/suggestions", params=params or None
+        )
+        return AliasSuggestions.model_validate(data)
+
+    @staticmethod
+    def in_use(error: BaseException) -> AliasImpact | None:
+        """The agents blocking a delete, when ``error`` is the 409 raised by
+        :meth:`remove`; ``None`` for any other error."""
+        if (
+            not isinstance(error, httpx.HTTPStatusError)
+            or error.response.status_code != 409
+        ):
+            return None
+        try:
+            impact = error.response.json()["detail"]["impact"]
+            if not isinstance(impact.get("total"), int):
+                return None
+            return AliasImpact.model_validate(impact)
+        except Exception:
+            return None

persona_sdk_python-0.2.26/persona_sdk/api/notifications.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+from persona_models.common import Paginated
+from persona_models.notifications import Notification
+
+from persona_sdk.client import PersonaClient
+
+
+class NotificationsApi:
+    """In-platform notifications. A project sees its own; platform-wide ones (no
+    project) are for super admins. Read state is shared by everyone who can see a
+    notification."""
+
+    def __init__(self, client: PersonaClient):
+        self._client = client
+
+    async def list(
+        self,
+        unread_only: bool = False,
+        include_resolved: bool = False,
+        project_id: str | None = None,
+        page: int = 1,
+        size: int = 20,
+    ) -> Paginated[Notification]:
+        params: dict[str, Any] = {"page": page, "size": size}
+        if unread_only:
+            params["unreadOnly"] = True
+        if include_resolved:
+            params["includeResolved"] = True
+        if project_id:
+            params["projectId"] = project_id
+        data = await self._client.get("/notifications", params=params)
+        return Paginated[Notification].model_validate(data)
+
+    async def unread_count(self, project_id: str | None = None) -> int:
+        """Open, unread notifications: the value of the badge."""
+        params = {"projectId": project_id} if project_id else None
+        data = await self._client.get("/notifications/unread-count", params=params)
+        return data["count"]
+
+    async def mark_read(self, notification_id: str) -> Notification:
+        data = await self._client.post(f"/notifications/{notification_id}/read")
+        return Notification.model_validate(data)
+
+    async def mark_all_read(self, project_id: str | None = None) -> None:
+        """Mark as read everything the caller can see."""
+        params = {"projectId": project_id} if project_id else None
+        await self._client.post("/notifications/read-all", params=params)

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/persona_sdk/client.py

@@ -8,6 +8,11 @@ from persona_sdk.auth import (
 )
 
 
+def _body(response: httpx.Response) -> Any:
+    """Decoded JSON body, or ``None`` for an empty one (e.g. ``204 No Content``)."""
+    return response.json() if response.content else None
+
+
 class PersonaClient:
     """
     HTTP client for the Persona API.
@@ -56,7 +61,7 @@ class PersonaClient:
     async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
         response = await self._client.get(path, params=params)
         response.raise_for_status()
-        return response.json()
+        return _body(response)
 
     async def post(
         self,
@@ -66,22 +71,22 @@ class PersonaClient:
     ) -> Any:
         response = await self._client.post(path, json=json, params=params)
         response.raise_for_status()
-        return response.json()
+        return _body(response)
 
     async def put(self, path: str, json: dict[str, Any] | None = None) -> Any:
         response = await self._client.put(path, json=json)
         response.raise_for_status()
-        return response.json()
+        return _body(response)
 
     async def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
         response = await self._client.patch(path, json=json)
         response.raise_for_status()
-        return response.json()
+        return _body(response)
 
     async def delete(self, path: str) -> Any:
         response = await self._client.delete(path)
         response.raise_for_status()
-        return response.json()
+        return _body(response)
 
     async def close(self):
         await self._client.aclose()

{persona_sdk_python-0.2.25 → persona_sdk_python-0.2.26}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "persona-sdk-python"
-version = "0.2.25"
+version = "0.2.26"
 description = "Async Python SDK for the Persona AI platform"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,7 +22,7 @@ classifiers = [
     "Framework :: AsyncIO",
 ]
 dependencies = [
-    "persona-models>=0.2.16",
+    "persona-models>=0.2.20",
     "httpx>=0.27.0",
 ]
 
@@ -36,3 +36,14 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["persona_sdk"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]

persona_sdk_python-0.2.26/tests/conftest.py

@@ -0,0 +1,53 @@
+import json
+from typing import Any, Callable
+
+import httpx
+import pytest
+
+from persona_sdk import PersonaSdk
+
+
+class Recorder:
+    """Records requests made through the SDK and answers with a canned response."""
+
+    def __init__(self):
+        self.calls: list[httpx.Request] = []
+        self.response: Callable[[httpx.Request], httpx.Response] = lambda r: httpx.Response(200, json={})
+
+    def reply(self, status: int = 200, body: Any = None):
+        def handler(request: httpx.Request) -> httpx.Response:
+            if body is None:
+                return httpx.Response(status)
+            return httpx.Response(status, json=body)
+
+        self.response = handler
+
+    @property
+    def last(self) -> httpx.Request:
+        return self.calls[-1]
+
+    def body(self) -> Any:
+        return json.loads(self.last.content)
+
+    def query(self) -> dict[str, list[str]]:
+        return {k: self.last.url.params.get_list(k) for k in self.last.url.params.keys()}
+
+
+@pytest.fixture
+async def mock():
+    rec = Recorder()
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        rec.calls.append(request)
+        return rec.response(request)
+
+    sdk = PersonaSdk("http://persona.test", "prs_test")
+    await sdk.client._client.aclose()
+    sdk.client._client = httpx.AsyncClient(
+        base_url="http://persona.test",
+        headers=sdk.client.auth_provider.headers(),
+        transport=httpx.MockTransport(handler),
+    )
+    rec.sdk = sdk
+    yield rec
+    await sdk.close()