p0aiapi 0.1.0__py3-none-any.whl

p0aiapi/__init__.py

@@ -0,0 +1,46 @@
+"""Public interface for p0aiapi."""
+
+from importlib.metadata import version
+
+from .catalog import load_catalog
+from .client import AsyncClient, Client, P0ResponseError
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    P0Error,
+    RateLimitError,
+    ServerError,
+    TaskFailedError,
+    TaskTimeoutError,
+    TransportError,
+    ValidationError,
+)
+from .models import TaskStatus
+from .openapi import OpenAPISchema, Operation, SchemaError, diff_schemas
+from .streaming import ServerSentEvent
+
+__version__ = version("p0aiapi")
+__all__ = [
+    "APIError",
+    "AsyncClient",
+    "AuthenticationError",
+    "Client",
+    "P0Error",
+    "P0ResponseError",
+    "NotFoundError",
+    "OpenAPISchema",
+    "Operation",
+    "RateLimitError",
+    "SchemaError",
+    "ServerError",
+    "ServerSentEvent",
+    "TaskFailedError",
+    "TaskStatus",
+    "TaskTimeoutError",
+    "TransportError",
+    "ValidationError",
+    "__version__",
+    "diff_schemas",
+    "load_catalog",
+]

p0aiapi/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

p0aiapi/audio.py

@@ -0,0 +1,117 @@
+"""Conveniences for the backend's public audio and TTS v2 APIs.
+
+Generation returns the initial task record. List and upload responses remain in
+the server's original shape, including fields introduced by later API versions.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+from .resources import _AsyncClient, _Client, _provided
+
+
+def _content_type(source: Path) -> str:
+    if source.suffix.lower() == ".wav":
+        return "audio/wav"
+    return mimetypes.guess_type(source.name)[0] or "application/octet-stream"
+
+
+class Audio:
+    """TTS v1 voice management and text-to-speech task submission."""
+
+    def __init__(self, client: _Client) -> None:
+        self._client = client
+
+    def list_voices(self) -> Any:
+        """Return the available voice IDs in the backend's response shape."""
+        return self._client.request("GET", "/api/public/generate/audio/list")
+
+    def generate(self, text: str, **fields: Any) -> Any:
+        """Submit audio generation; fields may include spk_id and task_id.
+
+        Optional values are omitted when None, so the backend controls defaults.
+        The SDK sends text unchanged; any further processing belongs to the API.
+        """
+        return self._client.request(
+            "POST", "/api/public/generate/audio", data=_provided({"text": text, **fields})
+        )
+
+    def upload_voice(self, spk_id: str, prompt_text: str, path: str | PathLike[str]) -> Any:
+        """Upload a local voice sample with its transcript.
+
+        The backend currently requires a WAV sample of 5–30 seconds. The local
+        file is closed whether the upload succeeds or raises an exception.
+        """
+        source = Path(path)
+        with source.open("rb") as stream:
+            return self._client.request(
+                "POST",
+                "/api/public/generate/audio/upload",
+                data={"spk_id": spk_id, "prompt_text": prompt_text},
+                files={"prompt_audio": (source.name, stream, _content_type(source))},
+            )
+
+
+class AsyncAudio:
+    """Asynchronous counterpart of :class:`Audio`."""
+
+    def __init__(self, client: _AsyncClient) -> None:
+        self._client = client
+
+    async def list_voices(self) -> Any:
+        return await self._client.request("GET", "/api/public/generate/audio/list")
+
+    async def generate(self, text: str, **fields: Any) -> Any:
+        return await self._client.request(
+            "POST", "/api/public/generate/audio", data=_provided({"text": text, **fields})
+        )
+
+    async def upload_voice(self, spk_id: str, prompt_text: str, path: str | PathLike[str]) -> Any:
+        """Upload a WAV sample and transcript; close the file after completion."""
+        source = Path(path)
+        with source.open("rb") as stream:
+            return await self._client.request(
+                "POST",
+                "/api/public/generate/audio/upload",
+                data={"spk_id": spk_id, "prompt_text": prompt_text},
+                files={"prompt_audio": (source.name, stream, _content_type(source))},
+            )
+
+
+class TTS:
+    """TTS v2 speaker management and text-to-speech task submission."""
+
+    def __init__(self, client: _Client) -> None:
+        self._client = client
+
+    def list_speakers(self) -> Any:
+        return self._client.request("GET", "/api/public/generate/ttsv2/speakers")
+
+    def generate(self, text: str, spk_id: str, **fields: Any) -> Any:
+        """Submit TTS v2; optional fields include use_emo, emo_type, and task_id."""
+        return self._client.request(
+            "POST",
+            "/api/public/generate/ttsv2",
+            data=_provided({"text": text, "spk_id": spk_id, **fields}),
+        )
+
+
+class AsyncTTS:
+    """Asynchronous counterpart of :class:`TTS`."""
+
+    def __init__(self, client: _AsyncClient) -> None:
+        self._client = client
+
+    async def list_speakers(self) -> Any:
+        return await self._client.request("GET", "/api/public/generate/ttsv2/speakers")
+
+    async def generate(self, text: str, spk_id: str, **fields: Any) -> Any:
+        return await self._client.request(
+            "POST",
+            "/api/public/generate/ttsv2",
+            data=_provided({"text": text, "spk_id": spk_id, **fields}),
+        )

p0aiapi/catalog.py

@@ -0,0 +1,21 @@
+"""Load the packaged, reviewed catalogue without a network request.
+
+The catalogue covers a supported subset of YApi project 8 matched to registered
+backend routes. It is neither the full backend API nor a live deployment schema.
+Use an explicitly fetched deployment schema when current server metadata is
+needed. Catalogue IDs such as ``yapi_2527`` remain independent of FastAPI's
+generated operation IDs.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib.resources import files
+
+from .openapi import OpenAPISchema
+
+
+def load_catalog() -> OpenAPISchema:
+    """Return a fresh offline schema containing the 27 reviewed YApi operations."""
+    resource = files("p0aiapi").joinpath("schemas").joinpath("yapi-8.openapi.json")
+    return OpenAPISchema(json.loads(resource.read_text(encoding="utf-8")))

p0aiapi/cli.py

@@ -0,0 +1,78 @@
+"""Download and inspect deployment-specific OpenAPI snapshots."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from .catalog import load_catalog
+from .client import DEFAULT_BASE_URL, Client
+from .exceptions import P0Error
+from .openapi import OpenAPISchema, diff_schemas
+
+
+def _write_snapshot(path: Path, document: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    filename = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, delete=False
+        ) as file:
+            filename = file.name
+            json.dump(document, file, ensure_ascii=False, indent=2)
+            file.write("\n")
+        os.replace(filename, path)
+    finally:
+        if filename is not None and os.path.exists(filename):
+            os.unlink(filename)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="p0aiapi", description="P0 OpenAPI snapshot tools")
+    sub = parser.add_subparsers(dest="command", required=True)
+    fetch = sub.add_parser("fetch-schema", help="Download and validate /openapi.json")
+    fetch.add_argument(
+        "--base-url", help=f"Service root; defaults to P0_API_BASE_URL or {DEFAULT_BASE_URL}"
+    )
+    fetch.add_argument("--path", default="/openapi.json", help="Schema path inside this deployment")
+    fetch.add_argument("--output", required=True, type=Path)
+    listing = sub.add_parser("operations", help="List operation IDs, HTTP methods and paths")
+    listing.add_argument("schema", type=Path, nargs="?", help="Defaults to the bundled catalog")
+    export = sub.add_parser("export-catalog", help="Save the bundled, verified YApi subset")
+    export.add_argument("--output", required=True, type=Path)
+    diff = sub.add_parser("diff", help="Compare two schema snapshots (not a compatibility proof)")
+    diff.add_argument("old", type=Path)
+    diff.add_argument("new", type=Path)
+    diff.add_argument("--fail-on-change", action="store_true", help="Exit 2 on any difference")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "fetch-schema":
+            with Client(args.base_url) as client:
+                schema = client.refresh_openapi(args.path)
+            _write_snapshot(args.output, schema.document)
+            print(f"Saved {len(schema.operations)} operations to {args.output}")
+        elif args.command == "operations":
+            schema = OpenAPISchema.load(args.schema) if args.schema else load_catalog()
+            for operation in schema.operations.values():
+                print(f"{operation.id}\t{operation.method}\t{operation.path}")
+        elif args.command == "export-catalog":
+            schema = load_catalog()
+            _write_snapshot(args.output, schema.document)
+            print(f"Saved {len(schema.operations)} bundled operations to {args.output}")
+        else:
+            result = diff_schemas(OpenAPISchema.load(args.old), OpenAPISchema.load(args.new))
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            if args.fail_on_change and any(result.values()):
+                return 2
+    except (P0Error, ValueError, OSError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())