promptrails 0.1.0__tar.gz

promptrails-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PromptRails
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptrails-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: promptrails
+Version: 0.1.0
+Summary: Official Python SDK for the PromptRails API
+Author-email: PromptRails <support@promptrails.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/promptrails/promptrails
+Project-URL: Documentation, https://promptrails.ai/docs
+Project-URL: Repository, https://github.com/promptrails/promptrails
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Dynamic: license-file
+
+# PromptRails Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/promptrails.svg)](https://pypi.org/project/promptrails/)
+[![Python versions](https://img.shields.io/pypi/pyversions/promptrails.svg)](https://pypi.org/project/promptrails/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for [PromptRails](https://promptrails.ai) — the AI agent orchestration platform.
+
+## Installation
+
+```bash
+pip install promptrails
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from promptrails import PromptRails
+
+client = PromptRails(api_key="pr_key_...")
+
+# Execute an agent
+result = client.agents.execute("agent-id", input={"query": "Summarise this week's sales"})
+print(result.output)
+
+client.close()
+```
+
+### Async
+
+```python
+import asyncio
+from promptrails import AsyncPromptRails
+
+async def main():
+    async with AsyncPromptRails(api_key="pr_key_...") as client:
+        result = await client.agents.execute("agent-id", input={"query": "hello"})
+        print(result.output)
+
+asyncio.run(main())
+```
+
+### Context Manager
+
+```python
+with PromptRails(api_key="pr_key_...") as client:
+    agents = client.agents.list()
+    for agent in agents.data:
+        print(agent.name)
+```
+
+## Error Handling
+
+```python
+from promptrails import NotFoundError, ValidationError, RateLimitError, QuotaExceededError
+
+try:
+    result = client.agents.execute("agent-id", input={})
+except QuotaExceededError:
+    print("Execution limit reached — upgrade your plan")
+except RateLimitError:
+    print("Too many requests, back off and retry")
+except NotFoundError as e:
+    print(f"Agent not found: {e.message}")
+```
+
+## Available Resources
+
+| Resource                  | Methods                                                                  |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `client.agents`           | `list`, `get`, `create`, `update`, `delete`, `execute`, `list_versions`, `create_version`, `list_guardrails`, `create_guardrail`, `list_memories`, `create_memory`, `search_memories`, `delete_all_memories` |
+| `client.prompts`          | `list`, `get`, `create`, `update`, `delete`, `list_versions`, `create_version` |
+| `client.executions`       | `list`, `get`                                                            |
+| `client.credentials`      | `list`, `get`, `create`, `update`, `delete`, `set_default`, `check_connection` |
+| `client.data_sources`     | `list`, `get`, `create`, `update`, `delete`, `list_versions`, `create_version`, `test_connection`, `query` |
+| `client.chat`             | `list_sessions`, `get_session`, `create_session`, `delete_session`, `list_messages`, `send_message` |
+| `client.traces`           | `list`, `get_by_trace_id`                                                |
+| `client.costs`            | `get_summary`, `get_agent_summary`                                       |
+| `client.scores`           | `list`, `get`, `create`, `update`, `delete`, `list_configs`, `get_config`, `create_config`, `update_config`, `delete_config`, `aggregates` |
+| `client.mcp_tools`        | `list`, `get`, `create`, `update`, `delete`                              |
+| `client.approvals`        | `list`, `get`, `decide`                                                  |
+| `client.webhook_triggers` | `list`, `get`, `create`, `update`, `delete`                              |
+| `client.a2a`              | `get_agent_card`, `send_message`, `get_task`, `list_tasks`, `cancel_task` |
+
+## Configuration
+
+| Option        | Default                      | Description                       |
+| ------------- | ---------------------------- | --------------------------------- |
+| `api_key`     | required                     | API key                           |
+| `base_url`    | `https://api.promptrails.ai` | API base URL                      |
+| `timeout`     | `30.0`                       | Request timeout (seconds)         |
+| `max_retries` | `3`                          | Max retries on network/5xx errors |
+
+## Contributing
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run linter
+ruff check .
+
+# Run formatter
+ruff format .
+
+# Run tests
+pytest tests/ -v
+```
+
+## License
+
+MIT

promptrails-0.1.0/README.md

@@ -0,0 +1,114 @@
+# PromptRails Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/promptrails.svg)](https://pypi.org/project/promptrails/)
+[![Python versions](https://img.shields.io/pypi/pyversions/promptrails.svg)](https://pypi.org/project/promptrails/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Python SDK for [PromptRails](https://promptrails.ai) — the AI agent orchestration platform.
+
+## Installation
+
+```bash
+pip install promptrails
+```
+
+## Quick Start
+
+### Synchronous
+
+```python
+from promptrails import PromptRails
+
+client = PromptRails(api_key="pr_key_...")
+
+# Execute an agent
+result = client.agents.execute("agent-id", input={"query": "Summarise this week's sales"})
+print(result.output)
+
+client.close()
+```
+
+### Async
+
+```python
+import asyncio
+from promptrails import AsyncPromptRails
+
+async def main():
+    async with AsyncPromptRails(api_key="pr_key_...") as client:
+        result = await client.agents.execute("agent-id", input={"query": "hello"})
+        print(result.output)
+
+asyncio.run(main())
+```
+
+### Context Manager
+
+```python
+with PromptRails(api_key="pr_key_...") as client:
+    agents = client.agents.list()
+    for agent in agents.data:
+        print(agent.name)
+```
+
+## Error Handling
+
+```python
+from promptrails import NotFoundError, ValidationError, RateLimitError, QuotaExceededError
+
+try:
+    result = client.agents.execute("agent-id", input={})
+except QuotaExceededError:
+    print("Execution limit reached — upgrade your plan")
+except RateLimitError:
+    print("Too many requests, back off and retry")
+except NotFoundError as e:
+    print(f"Agent not found: {e.message}")
+```
+
+## Available Resources
+
+| Resource                  | Methods                                                                  |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `client.agents`           | `list`, `get`, `create`, `update`, `delete`, `execute`, `list_versions`, `create_version`, `list_guardrails`, `create_guardrail`, `list_memories`, `create_memory`, `search_memories`, `delete_all_memories` |
+| `client.prompts`          | `list`, `get`, `create`, `update`, `delete`, `list_versions`, `create_version` |
+| `client.executions`       | `list`, `get`                                                            |
+| `client.credentials`      | `list`, `get`, `create`, `update`, `delete`, `set_default`, `check_connection` |
+| `client.data_sources`     | `list`, `get`, `create`, `update`, `delete`, `list_versions`, `create_version`, `test_connection`, `query` |
+| `client.chat`             | `list_sessions`, `get_session`, `create_session`, `delete_session`, `list_messages`, `send_message` |
+| `client.traces`           | `list`, `get_by_trace_id`                                                |
+| `client.costs`            | `get_summary`, `get_agent_summary`                                       |
+| `client.scores`           | `list`, `get`, `create`, `update`, `delete`, `list_configs`, `get_config`, `create_config`, `update_config`, `delete_config`, `aggregates` |
+| `client.mcp_tools`        | `list`, `get`, `create`, `update`, `delete`                              |
+| `client.approvals`        | `list`, `get`, `decide`                                                  |
+| `client.webhook_triggers` | `list`, `get`, `create`, `update`, `delete`                              |
+| `client.a2a`              | `get_agent_card`, `send_message`, `get_task`, `list_tasks`, `cancel_task` |
+
+## Configuration
+
+| Option        | Default                      | Description                       |
+| ------------- | ---------------------------- | --------------------------------- |
+| `api_key`     | required                     | API key                           |
+| `base_url`    | `https://api.promptrails.ai` | API base URL                      |
+| `timeout`     | `30.0`                       | Request timeout (seconds)         |
+| `max_retries` | `3`                          | Max retries on network/5xx errors |
+
+## Contributing
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run linter
+ruff check .
+
+# Run formatter
+ruff format .
+
+# Run tests
+pytest tests/ -v
+```
+
+## License
+
+MIT

promptrails-0.1.0/promptrails/__init__.py

@@ -0,0 +1,90 @@
+"""PromptRails Python SDK."""
+
+from .async_client import AsyncPromptRails
+from .client import PromptRails
+from .exceptions import (
+    ForbiddenError,
+    NotFoundError,
+    PromptRailsError,
+    RateLimitError,
+    ServerError,
+    UnauthorizedError,
+    ValidationError,
+)
+from .pagination import PaginatedResponse, PaginationMeta
+from .types import (
+    Agent,
+    AgentExecution,
+    AgentMemory,
+    AgentVersion,
+    ApprovalRequest,
+    AvailableModelEntry,
+    AvailableModelGroup,
+    ChatMessage,
+    ChatSession,
+    CostSummary,
+    Credential,
+    DataSource,
+    DataSourceVersion,
+    ExecutionResult,
+    FlowTemplate,
+    Guardrail,
+    InstallMCPTemplateRequest,
+    LLMModel,
+    MCPCallToolResult,
+    MCPDiscoveredTool,
+    MCPDiscoverResult,
+    MCPTemplate,
+    MCPTemplateParameterSpec,
+    MCPTool,
+    MCPToolCallContent,
+    Prompt,
+    PromptVersion,
+    RunPromptResponse,
+    Trace,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Agent",
+    "AgentExecution",
+    "AgentMemory",
+    "AgentVersion",
+    "ApprovalRequest",
+    "AsyncPromptRails",
+    "AvailableModelEntry",
+    "AvailableModelGroup",
+    "ChatMessage",
+    "ChatSession",
+    "CostSummary",
+    "Credential",
+    "DataSource",
+    "DataSourceVersion",
+    "ExecutionResult",
+    "FlowTemplate",
+    "ForbiddenError",
+    "Guardrail",
+    "InstallMCPTemplateRequest",
+    "LLMModel",
+    "MCPCallToolResult",
+    "MCPDiscoverResult",
+    "MCPDiscoveredTool",
+    "MCPTemplate",
+    "MCPTemplateParameterSpec",
+    "MCPTool",
+    "MCPToolCallContent",
+    "NotFoundError",
+    "PaginatedResponse",
+    "PaginationMeta",
+    "Prompt",
+    "PromptRails",
+    "PromptRailsError",
+    "PromptVersion",
+    "RateLimitError",
+    "RunPromptResponse",
+    "ServerError",
+    "Trace",
+    "UnauthorizedError",
+    "ValidationError",
+]

promptrails-0.1.0/promptrails/_async_http.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .config import Config
+from .exceptions import RateLimitError, ServerError, raise_for_status
+
+
+class AsyncHTTPClient:
+    """Async HTTP wrapper around httpx."""
+
+    def __init__(self, config: Config):
+        self._config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers=config.headers,
+            timeout=config.timeout,
+        )
+
+    async def close(self):
+        await self._client.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.request(method, path, json=json, params=params)
+                body = response.json() if response.content else {}
+                if response.status_code >= 500:
+                    raise ServerError(
+                        message=body.get("error", "Server error"),
+                        status_code=response.status_code,
+                    )
+                raise_for_status(response.status_code, body)
+                return body
+            except (httpx.ConnectError, httpx.TimeoutException, ServerError):
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(min(2**attempt, 8))
+                    continue
+                raise
+            except RateLimitError:
+                raise
+
+    async def get(self, path: str, **kwargs) -> Dict[str, Any]:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs) -> Dict[str, Any]:
+        return await self.request("POST", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs) -> Dict[str, Any]:
+        return await self.request("PATCH", path, **kwargs)
+
+    async def put(self, path: str, **kwargs) -> Dict[str, Any]:
+        return await self.request("PUT", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs) -> Dict[str, Any]:
+        return await self.request("DELETE", path, **kwargs)

promptrails-0.1.0/promptrails/_http.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .config import Config
+from .exceptions import RateLimitError, ServerError, raise_for_status
+
+
+class HTTPClient:
+    """Synchronous HTTP wrapper around httpx."""
+
+    def __init__(self, config: Config):
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            headers=config.headers,
+            timeout=config.timeout,
+        )
+
+    def close(self):
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.request(method, path, json=json, params=params)
+                body = response.json() if response.content else {}
+                if response.status_code >= 500:
+                    raise ServerError(
+                        message=body.get("error", "Server error"),
+                        status_code=response.status_code,
+                    )
+                raise_for_status(response.status_code, body)
+                return body
+            except (httpx.ConnectError, httpx.TimeoutException, ServerError):
+                if attempt < self._config.max_retries:
+                    time.sleep(min(2**attempt, 8))
+                    continue
+                raise
+            except RateLimitError:
+                raise
+
+    def get(self, path: str, **kwargs) -> Dict[str, Any]:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs) -> Dict[str, Any]:
+        return self.request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs) -> Dict[str, Any]:
+        return self.request("PATCH", path, **kwargs)
+
+    def put(self, path: str, **kwargs) -> Dict[str, Any]:
+        return self.request("PUT", path, **kwargs)
+
+    def delete(self, path: str, **kwargs) -> Dict[str, Any]:
+        return self.request("DELETE", path, **kwargs)

promptrails-0.1.0/promptrails/async_client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from ._async_http import AsyncHTTPClient
+from .config import Config
+from .resources import (
+    AsyncA2AResource,
+    AsyncAgentsResource,
+    AsyncApprovalsResource,
+    AsyncChatResource,
+    AsyncCostsResource,
+    AsyncCredentialsResource,
+    AsyncDashboardResource,
+    AsyncDataSourcesResource,
+    AsyncExecutionsResource,
+    AsyncGuardrailsResource,
+    AsyncLLMModelsResource,
+    AsyncMCPTemplatesResource,
+    AsyncMCPToolsResource,
+    AsyncMemoriesResource,
+    AsyncPromptsResource,
+    AsyncScoresResource,
+    AsyncSessionsResource,
+    AsyncTemplatesResource,
+    AsyncTracesResource,
+    AsyncWebhookTriggersResource,
+)
+
+
+class AsyncPromptRails:
+    """Async PromptRails API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.promptrails.ai",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self._config = Config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = AsyncHTTPClient(self._config)
+
+        self.agents = AsyncAgentsResource(self._http)
+        self.prompts = AsyncPromptsResource(self._http)
+        self.executions = AsyncExecutionsResource(self._http)
+        self.credentials = AsyncCredentialsResource(self._http)
+        self.data_sources = AsyncDataSourcesResource(self._http)
+        self.chat = AsyncChatResource(self._http)
+        self.memories = AsyncMemoriesResource(self._http)
+        self.traces = AsyncTracesResource(self._http)
+        self.costs = AsyncCostsResource(self._http)
+        self.mcp_tools = AsyncMCPToolsResource(self._http)
+        self.mcp_templates = AsyncMCPTemplatesResource(self._http)
+        self.guardrails = AsyncGuardrailsResource(self._http)
+        self.llm_models = AsyncLLMModelsResource(self._http)
+        self.approvals = AsyncApprovalsResource(self._http)
+        self.templates = AsyncTemplatesResource(self._http)
+        self.scores = AsyncScoresResource(self._http)
+        self.dashboard = AsyncDashboardResource(self._http)
+        self.sessions = AsyncSessionsResource(self._http)
+        self.a2a = AsyncA2AResource(self._http)
+        self.webhook_triggers = AsyncWebhookTriggersResource(self._http)
+
+    async def close(self):
+        """Close the underlying HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

promptrails-0.1.0/promptrails/client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from ._http import HTTPClient
+from .config import Config
+from .resources import (
+    A2AResource,
+    AgentsResource,
+    ApprovalsResource,
+    ChatResource,
+    CostsResource,
+    CredentialsResource,
+    DashboardResource,
+    DataSourcesResource,
+    ExecutionsResource,
+    GuardrailsResource,
+    LLMModelsResource,
+    MCPTemplatesResource,
+    MCPToolsResource,
+    MemoriesResource,
+    PromptsResource,
+    ScoresResource,
+    SessionsResource,
+    TemplatesResource,
+    TracesResource,
+    WebhookTriggersResource,
+)
+
+
+class PromptRails:
+    """Synchronous PromptRails API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.promptrails.ai",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ):
+        self._config = Config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = HTTPClient(self._config)
+
+        self.agents = AgentsResource(self._http)
+        self.prompts = PromptsResource(self._http)
+        self.executions = ExecutionsResource(self._http)
+        self.credentials = CredentialsResource(self._http)
+        self.data_sources = DataSourcesResource(self._http)
+        self.chat = ChatResource(self._http)
+        self.memories = MemoriesResource(self._http)
+        self.traces = TracesResource(self._http)
+        self.costs = CostsResource(self._http)
+        self.mcp_tools = MCPToolsResource(self._http)
+        self.mcp_templates = MCPTemplatesResource(self._http)
+        self.guardrails = GuardrailsResource(self._http)
+        self.llm_models = LLMModelsResource(self._http)
+        self.approvals = ApprovalsResource(self._http)
+        self.templates = TemplatesResource(self._http)
+        self.scores = ScoresResource(self._http)
+        self.dashboard = DashboardResource(self._http)
+        self.sessions = SessionsResource(self._http)
+        self.a2a = A2AResource(self._http)
+        self.webhook_triggers = WebhookTriggersResource(self._http)
+
+    def close(self):
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

promptrails-0.1.0/promptrails/config.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    api_key: str
+    base_url: str = "https://api.promptrails.ai"
+    timeout: float = 30.0
+    max_retries: int = 3
+
+    def __post_init__(self):
+        self.base_url = self.base_url.rstrip("/")
+
+    @property
+    def headers(self) -> dict:
+        return {
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }