promptjuggler 0.1.0__tar.gz

promptjuggler-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+/dist/
+/build/
+*.egg-info/
+.venv/

promptjuggler-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: promptjuggler
+Version: 0.1.0
+Summary: Python SDK for the PromptJuggler API — run prompts and workflows, manage knowledge bases, and verify webhooks.
+Project-URL: Homepage, https://docs.promptjuggler.com/sdks/python/overview
+Project-URL: Repository, https://github.com/motleyhand/promptjuggler-python-sdk
+Author: PromptJuggler
+License-Expression: MIT
+Keywords: ai,llm,promptjuggler,prompts,sdk
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: typing-extensions>=4.7
+Requires-Dist: urllib3>=2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PromptJuggler Python SDK
+
+The official Python client for the [PromptJuggler](https://promptjuggler.com) API. Run
+prompts and workflows, manage knowledge bases, and verify webhooks — with pydantic-typed
+models and flat, synchronous methods.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install promptjuggler
+```
+
+## Usage
+
+```python
+from promptjuggler import PromptJuggler, RunStatus
+
+pj = PromptJuggler("your-api-key")
+
+# Trigger a run (async — returns the run ID)
+created = pj.run_prompt("greeting", "production", {"name": "Ada"})
+
+# Poll for the result
+run = pj.get_prompt_run(created.id)
+if run.status == RunStatus.COMPLETED:
+    print(run.output)
+```
+
+Errors surface as `ApiError` (with a `status_code`). Verify incoming webhooks with
+`verify_webhook_signature()`.
+
+## Documentation
+
+Full guides and the API reference: **https://docs.promptjuggler.com/sdks/python/overview**
+
+## License
+
+MIT

promptjuggler-0.1.0/README.md

@@ -0,0 +1,42 @@
+# PromptJuggler Python SDK
+
+The official Python client for the [PromptJuggler](https://promptjuggler.com) API. Run
+prompts and workflows, manage knowledge bases, and verify webhooks — with pydantic-typed
+models and flat, synchronous methods.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install promptjuggler
+```
+
+## Usage
+
+```python
+from promptjuggler import PromptJuggler, RunStatus
+
+pj = PromptJuggler("your-api-key")
+
+# Trigger a run (async — returns the run ID)
+created = pj.run_prompt("greeting", "production", {"name": "Ada"})
+
+# Poll for the result
+run = pj.get_prompt_run(created.id)
+if run.status == RunStatus.COMPLETED:
+    print(run.output)
+```
+
+Errors surface as `ApiError` (with a `status_code`). Verify incoming webhooks with
+`verify_webhook_signature()`.
+
+## Documentation
+
+Full guides and the API reference: **https://docs.promptjuggler.com/sdks/python/overview**
+
+## License
+
+MIT

promptjuggler-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "promptjuggler"
+version = "0.1.0"
+description = "Python SDK for the PromptJuggler API — run prompts and workflows, manage knowledge bases, and verify webhooks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "PromptJuggler" }]
+keywords = ["promptjuggler", "llm", "prompts", "ai", "sdk"]
+dependencies = [
+  "pydantic>=2",
+  "urllib3>=2",
+  "python-dateutil>=2.8",
+  "typing-extensions>=4.7",
+]
+
+[project.urls]
+Homepage = "https://docs.promptjuggler.com/sdks/python/overview"
+Repository = "https://github.com/motleyhand/promptjuggler-python-sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.13", "ruff>=0.8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/promptjuggler"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+
+[tool.ruff]
+line-length = 110
+src = ["src", "tests"]
+# The generated client carries its own style; it's verified by the drift-check, not ruff.
+extend-exclude = ["src/promptjuggler/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+# The generated client is third-party-style code; type-check only our facade.
+files = ["src/promptjuggler", "tests"]
+exclude = "src/promptjuggler/_generated"
+
+[[tool.mypy.overrides]]
+module = "promptjuggler._generated.*"
+follow_untyped_imports = true

promptjuggler-0.1.0/src/promptjuggler/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from promptjuggler._client import PromptJuggler
+from promptjuggler._generated.models.create_prompt_run_response import CreatePromptRunResponse
+from promptjuggler._generated.models.create_workflow_run_response import CreateWorkflowRunResponse
+from promptjuggler._generated.models.knowledge_base_response import KnowledgeBaseResponse
+from promptjuggler._generated.models.knowledge_document_response import KnowledgeDocumentResponse
+from promptjuggler._generated.models.prompt_revision import PromptRevision
+from promptjuggler._generated.models.prompt_run import PromptRun
+from promptjuggler._generated.models.run_status import RunStatus
+from promptjuggler._generated.models.workflow_run import WorkflowRun
+from promptjuggler.errors import ApiError, NetworkError, PromptJugglerError
+from promptjuggler.webhook import verify_webhook_signature
+
+__all__ = [
+    "PromptJuggler",
+    "ApiError",
+    "NetworkError",
+    "PromptJugglerError",
+    "verify_webhook_signature",
+    "CreatePromptRunResponse",
+    "CreateWorkflowRunResponse",
+    "KnowledgeBaseResponse",
+    "KnowledgeDocumentResponse",
+    "PromptRevision",
+    "PromptRun",
+    "RunStatus",
+    "WorkflowRun",
+]

promptjuggler-0.1.0/src/promptjuggler/_client.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any, TypeVar, cast
+from uuid import UUID
+
+import urllib3.exceptions
+
+from promptjuggler._generated.api.knowledge_bases_api import KnowledgeBasesApi
+from promptjuggler._generated.api.prompt_runs_api import PromptRunsApi
+from promptjuggler._generated.api.prompts_api import PromptsApi
+from promptjuggler._generated.api.workflow_runs_api import WorkflowRunsApi
+from promptjuggler._generated.api_client import ApiClient
+from promptjuggler._generated.configuration import Configuration
+from promptjuggler._generated.exceptions import ApiException
+from promptjuggler._generated.models.create_prompt_run import CreatePromptRun
+from promptjuggler._generated.models.create_prompt_run_response import CreatePromptRunResponse
+from promptjuggler._generated.models.create_workflow_run import CreateWorkflowRun
+from promptjuggler._generated.models.create_workflow_run_metadata_value import CreateWorkflowRunMetadataValue
+from promptjuggler._generated.models.create_workflow_run_response import CreateWorkflowRunResponse
+from promptjuggler._generated.models.knowledge_base_response import KnowledgeBaseResponse
+from promptjuggler._generated.models.knowledge_document_response import KnowledgeDocumentResponse
+from promptjuggler._generated.models.prompt_revision import PromptRevision
+from promptjuggler._generated.models.prompt_run import PromptRun
+from promptjuggler._generated.models.workflow_run import WorkflowRun
+from promptjuggler.errors import ApiError, NetworkError
+
+DEFAULT_BASE_URL = "https://promptjuggler.com"
+
+T = TypeVar("T")
+
+# Metadata values are strings or lists of strings; the generated model wraps them in a
+# oneOf type, so the facade hides that wrapping.
+Metadata = dict[str, "str | list[str]"]
+
+
+class PromptJuggler:
+    """Ergonomic entry point to the PromptJuggler API. Wraps the generated client: flat
+    method calls in, generated typed (pydantic) models out, with API errors translated
+    into :class:`~promptjuggler.errors.ApiError`.
+    """
+
+    def __init__(self, api_key: str, *, base_url: str | None = None) -> None:
+        config = Configuration(host=base_url or DEFAULT_BASE_URL, access_token=api_key)
+        client = ApiClient(config)
+        self._prompts = PromptsApi(client)
+        self._prompt_runs = PromptRunsApi(client)
+        self._workflow_runs = WorkflowRunsApi(client)
+        self._knowledge_bases = KnowledgeBasesApi(client)
+
+    def get_prompt(self, slug: str, version: int | str) -> PromptRevision:
+        """Fetch a prompt revision by slug and version (a revision number or a tag like ``production``)."""
+        return self._send(lambda: self._prompts.get_prompt_revision(slug, str(version)))
+
+    def run_prompt(
+        self,
+        slug: str,
+        version: int | str,
+        inputs: dict[str, str],
+        *,
+        priority: str | None = None,
+        thread: str | UUID | None = None,
+        environment: str | None = None,
+        env_vars: dict[str, str] | None = None,
+        metadata: Metadata | None = None,
+        channel: str | None = None,
+    ) -> CreatePromptRunResponse:
+        """Trigger a prompt run (async — returns the run ID; poll :meth:`get_prompt_run` for the result)."""
+        body = CreatePromptRun(
+            inputs=inputs,
+            priority=priority,
+            thread=_uuid(thread) if thread is not None else None,
+            environment=environment,
+            envVars=env_vars,
+            metadata=_wrap_metadata(metadata),
+            channel=channel,
+        )
+        return self._send(lambda: self._prompt_runs.create_prompt_run(slug, str(version), body))
+
+    def get_prompt_run(self, run_id: str | UUID) -> PromptRun:
+        """Fetch a prompt run by ID."""
+        return self._send(lambda: self._prompt_runs.get_prompt_run(_uuid(run_id)))
+
+    def run_workflow(
+        self,
+        slug: str,
+        version: int | str,
+        inputs: dict[str, str],
+        *,
+        priority: str | None = None,
+        thread: str | UUID | None = None,
+        environment: str | None = None,
+        env_vars: dict[str, str] | None = None,
+        metadata: Metadata | None = None,
+    ) -> CreateWorkflowRunResponse:
+        """Trigger a workflow run (async — returns the run ID; poll :meth:`get_workflow_run`)."""
+        body = CreateWorkflowRun(
+            inputs=inputs,
+            priority=priority,
+            thread=_uuid(thread) if thread is not None else None,
+            environment=environment,
+            envVars=env_vars,
+            metadata=_wrap_metadata(metadata),
+        )
+        return self._send(lambda: self._workflow_runs.create_workflow_run(slug, str(version), body))
+
+    def get_workflow_run(self, run_id: str | UUID) -> WorkflowRun:
+        """Fetch a workflow run by ID."""
+        return self._send(lambda: self._workflow_runs.get_workflow_run(_uuid(run_id)))
+
+    def get_knowledge_base(self, slug: str) -> KnowledgeBaseResponse:
+        """Fetch a knowledge base by slug."""
+        return self._send(lambda: self._knowledge_bases.public_get_knowledge_base(slug))
+
+    def get_knowledge_document(self, document_id: str | UUID) -> KnowledgeDocumentResponse:
+        """Fetch a knowledge document by ID."""
+        return self._send(lambda: self._knowledge_bases.public_get_document(_uuid(document_id)))
+
+    def delete_knowledge_document(self, document_id: str | UUID) -> None:
+        """Delete a knowledge document by ID."""
+        self._send(lambda: self._knowledge_bases.public_delete_document(_uuid(document_id)))
+
+    def upload_documents(self, slug: str, files: list[tuple[str, bytes]]) -> list[KnowledgeDocumentResponse]:
+        """Upload one or more documents to a knowledge base (processed asynchronously).
+
+        Each file is a ``(filename, contents)`` tuple.
+        """
+        api = self._knowledge_bases
+        # The generated serializer names every multipart part "files"; the server needs
+        # them bracket-indexed (files[0], files[1], ...) to parse them as an array. Reuse
+        # the serializer (it builds the URL, auth, and (filename, bytes, mime) parts),
+        # rename the fields, and call through — the Python analogue of an init override.
+        method, url, headers, body, post_params = api._public_upload_documents_serialize(
+            slug=slug,
+            files=list(files),
+            _request_auth=None,
+            _content_type=None,
+            _headers=None,
+            _host_index=0,
+        )
+        bracketed = _bracket_file_fields(cast("list[tuple[str, Any]]", post_params))
+
+        def call() -> list[KnowledgeDocumentResponse]:
+            response = api.api_client.call_api(method, url, headers, body, bracketed)
+            response.read()
+            result = api.api_client.response_deserialize(
+                response, {"200": "List[KnowledgeDocumentResponse]", "403": "ErrorResponse"}
+            ).data
+            return cast("list[KnowledgeDocumentResponse]", result)
+
+        return self._send(call)
+
+    def _send(self, call: Callable[[], T]) -> T:
+        try:
+            return call()
+        except ApiException as error:
+            raise _to_api_error(error) from error
+        except urllib3.exceptions.HTTPError as error:
+            # No response: DNS failure, timeout, refused connection, etc.
+            raise NetworkError(str(error)) from error
+
+
+def _uuid(value: str | UUID) -> UUID:
+    return value if isinstance(value, UUID) else UUID(value)
+
+
+def _bracket_file_fields(post_params: list[tuple[str, Any]]) -> list[tuple[str, Any]]:
+    bracketed: list[tuple[str, Any]] = []
+    index = 0
+    for name, value in post_params:
+        if name == "files":
+            bracketed.append((f"files[{index}]", value))
+            index += 1
+        else:
+            bracketed.append((name, value))
+    return bracketed
+
+
+def _wrap_metadata(metadata: Metadata | None) -> dict[str, CreateWorkflowRunMetadataValue] | None:
+    if metadata is None:
+        return None
+    return {key: CreateWorkflowRunMetadataValue(value) for key, value in metadata.items()}
+
+
+def _to_api_error(error: ApiException) -> ApiError:
+    message = error.reason or "API request failed"
+    body = error.body
+    if isinstance(body, (str, bytes)):
+        try:
+            decoded = json.loads(body)
+        except (ValueError, TypeError):
+            decoded = None
+        if isinstance(decoded, dict) and isinstance(decoded.get("error"), str):
+            message = decoded["error"]
+    return ApiError(message, error.status)

promptjuggler-0.1.0/src/promptjuggler/_generated/__init__.py

@@ -0,0 +1,136 @@
+# coding: utf-8
+
+# flake8: noqa
+
+"""
+    PromptJuggler
+
+    PromptJuggler API
+
+    The version of the OpenAPI document: 1.0.0
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+__version__ = "1.0.0"
+
+# Define package exports
+__all__ = [
+    "KnowledgeBasesApi",
+    "PromptRunsApi",
+    "PromptsApi",
+    "WorkflowRunsApi",
+    "ApiResponse",
+    "ApiClient",
+    "Configuration",
+    "OpenApiException",
+    "ApiTypeError",
+    "ApiValueError",
+    "ApiKeyError",
+    "ApiAttributeError",
+    "ApiException",
+    "ContentMessageResponse",
+    "CreatePromptRun",
+    "CreatePromptRunResponse",
+    "CreateWorkflowRun",
+    "CreateWorkflowRunMetadataValue",
+    "CreateWorkflowRunResponse",
+    "ErrorResponse",
+    "HttpCall",
+    "HttpHeader",
+    "JsonObjectFormat",
+    "JsonSchemaFormat",
+    "KnowledgeBaseFinished",
+    "KnowledgeBaseResponse",
+    "KnowledgeBaseStatus",
+    "KnowledgeDocumentFinished",
+    "KnowledgeDocumentResponse",
+    "KnowledgeDocumentStatus",
+    "KnowledgeDocumentSummary",
+    "KnowledgeSearch",
+    "Mcp",
+    "Memory",
+    "Model",
+    "ModelParams",
+    "PromptCall",
+    "PromptRevision",
+    "PromptRun",
+    "PromptRunFinished",
+    "Provider",
+    "ResponseFormat",
+    "Role",
+    "RunStatus",
+    "ScriptCall",
+    "ServiceTier",
+    "TextFormat",
+    "Tool",
+    "VersionRef",
+    "VersionRefIdOrTag",
+    "WebSearch",
+    "WorkflowCall",
+    "WorkflowRun",
+    "WorkflowRunFinished",
+]
+
+# import apis into sdk package
+from promptjuggler._generated.api.knowledge_bases_api import KnowledgeBasesApi as KnowledgeBasesApi
+from promptjuggler._generated.api.prompt_runs_api import PromptRunsApi as PromptRunsApi
+from promptjuggler._generated.api.prompts_api import PromptsApi as PromptsApi
+from promptjuggler._generated.api.workflow_runs_api import WorkflowRunsApi as WorkflowRunsApi
+
+# import ApiClient
+from promptjuggler._generated.api_response import ApiResponse as ApiResponse
+from promptjuggler._generated.api_client import ApiClient as ApiClient
+from promptjuggler._generated.configuration import Configuration as Configuration
+from promptjuggler._generated.exceptions import OpenApiException as OpenApiException
+from promptjuggler._generated.exceptions import ApiTypeError as ApiTypeError
+from promptjuggler._generated.exceptions import ApiValueError as ApiValueError
+from promptjuggler._generated.exceptions import ApiKeyError as ApiKeyError
+from promptjuggler._generated.exceptions import ApiAttributeError as ApiAttributeError
+from promptjuggler._generated.exceptions import ApiException as ApiException
+
+# import models into sdk package
+from promptjuggler._generated.models.content_message_response import ContentMessageResponse as ContentMessageResponse
+from promptjuggler._generated.models.create_prompt_run import CreatePromptRun as CreatePromptRun
+from promptjuggler._generated.models.create_prompt_run_response import CreatePromptRunResponse as CreatePromptRunResponse
+from promptjuggler._generated.models.create_workflow_run import CreateWorkflowRun as CreateWorkflowRun
+from promptjuggler._generated.models.create_workflow_run_metadata_value import CreateWorkflowRunMetadataValue as CreateWorkflowRunMetadataValue
+from promptjuggler._generated.models.create_workflow_run_response import CreateWorkflowRunResponse as CreateWorkflowRunResponse
+from promptjuggler._generated.models.error_response import ErrorResponse as ErrorResponse
+from promptjuggler._generated.models.http_call import HttpCall as HttpCall
+from promptjuggler._generated.models.http_header import HttpHeader as HttpHeader
+from promptjuggler._generated.models.json_object_format import JsonObjectFormat as JsonObjectFormat
+from promptjuggler._generated.models.json_schema_format import JsonSchemaFormat as JsonSchemaFormat
+from promptjuggler._generated.models.knowledge_base_finished import KnowledgeBaseFinished as KnowledgeBaseFinished
+from promptjuggler._generated.models.knowledge_base_response import KnowledgeBaseResponse as KnowledgeBaseResponse
+from promptjuggler._generated.models.knowledge_base_status import KnowledgeBaseStatus as KnowledgeBaseStatus
+from promptjuggler._generated.models.knowledge_document_finished import KnowledgeDocumentFinished as KnowledgeDocumentFinished
+from promptjuggler._generated.models.knowledge_document_response import KnowledgeDocumentResponse as KnowledgeDocumentResponse
+from promptjuggler._generated.models.knowledge_document_status import KnowledgeDocumentStatus as KnowledgeDocumentStatus
+from promptjuggler._generated.models.knowledge_document_summary import KnowledgeDocumentSummary as KnowledgeDocumentSummary
+from promptjuggler._generated.models.knowledge_search import KnowledgeSearch as KnowledgeSearch
+from promptjuggler._generated.models.mcp import Mcp as Mcp
+from promptjuggler._generated.models.memory import Memory as Memory
+from promptjuggler._generated.models.model import Model as Model
+from promptjuggler._generated.models.model_params import ModelParams as ModelParams
+from promptjuggler._generated.models.prompt_call import PromptCall as PromptCall
+from promptjuggler._generated.models.prompt_revision import PromptRevision as PromptRevision
+from promptjuggler._generated.models.prompt_run import PromptRun as PromptRun
+from promptjuggler._generated.models.prompt_run_finished import PromptRunFinished as PromptRunFinished
+from promptjuggler._generated.models.provider import Provider as Provider
+from promptjuggler._generated.models.response_format import ResponseFormat as ResponseFormat
+from promptjuggler._generated.models.role import Role as Role
+from promptjuggler._generated.models.run_status import RunStatus as RunStatus
+from promptjuggler._generated.models.script_call import ScriptCall as ScriptCall
+from promptjuggler._generated.models.service_tier import ServiceTier as ServiceTier
+from promptjuggler._generated.models.text_format import TextFormat as TextFormat
+from promptjuggler._generated.models.tool import Tool as Tool
+from promptjuggler._generated.models.version_ref import VersionRef as VersionRef
+from promptjuggler._generated.models.version_ref_id_or_tag import VersionRefIdOrTag as VersionRefIdOrTag
+from promptjuggler._generated.models.web_search import WebSearch as WebSearch
+from promptjuggler._generated.models.workflow_call import WorkflowCall as WorkflowCall
+from promptjuggler._generated.models.workflow_run import WorkflowRun as WorkflowRun
+from promptjuggler._generated.models.workflow_run_finished import WorkflowRunFinished as WorkflowRunFinished
+

promptjuggler-0.1.0/src/promptjuggler/_generated/api/__init__.py

@@ -0,0 +1,8 @@
+# flake8: noqa
+
+# import apis into api package
+from promptjuggler._generated.api.knowledge_bases_api import KnowledgeBasesApi
+from promptjuggler._generated.api.prompt_runs_api import PromptRunsApi
+from promptjuggler._generated.api.prompts_api import PromptsApi
+from promptjuggler._generated.api.workflow_runs_api import WorkflowRunsApi
+