opus-aaico 0.1.0__tar.gz

opus_aaico-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

opus_aaico-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AAICO
+
+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.

opus_aaico-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: opus-aaico
+Version: 0.1.0
+Summary: Official Python SDK for the OPUS workflow automation platform
+Project-URL: Homepage, https://opus.com
+Project-URL: Documentation, https://docs.opus.com/sdk/python
+Project-URL: Repository, https://github.com/aaico/opus-aaico-python
+Author-email: AAICO <support@aaico.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aaico,ai,automation,opus,sdk,workflow
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opus-aaico
+
+Official Python SDK for the [OPUS](https://opus.com) workflow automation platform.
+
+Features:
+- Full coverage of all OPUS API endpoints (64 endpoints)
+- Sync and async clients
+- Type-safe with Pydantic models
+- Automatic retry with exponential backoff
+- High-level `workflows.run()` orchestrator
+
+## Installation
+
+```
+pip install opus-aaico
+```
+
+## Quick Start
+
+```python
+from opus_aaico import OpusClient
+
+client = OpusClient(api_key="your-api-key")
+
+# Run a workflow end-to-end (initiate -> execute -> poll -> results)
+result = client.workflows.run(
+    workflow_id="wf-123",
+    payload={"query": {"value": "Analyze this", "type": "str"}},
+)
+print(result.outputs)
+```
+
+## Authentication
+
+```python
+# Pass directly
+client = OpusClient(api_key="sk-...")
+
+# Or set environment variables
+# OPUS_API_KEY=sk-...
+# OPUS_WORKSPACE_ID=ws-...  (optional)
+# OPUS_BASE_URL=https://custom.opus.com  (optional)
+client = OpusClient()
+```
+
+## Resources
+
+| Resource | Methods | Description |
+|----------|---------|-------------|
+| `client.workflows` | get, list, list_public, generate, run, share, send_email... | Workflow management + orchestration |
+| `client.jobs` | initiate, execute, get_status, get_results, poll, search... | Job lifecycle management |
+| `client.files` | upload, download, search, generate, multipart_upload... | File operations |
+| `client.reviews` | initiate, list, get, pick, submit_result, submit_output... | Human review management |
+| `client.api_keys` | create, list, rotate, revoke, delete... | API key management |
+| `client.credits` | get_balance, get_usage, record_usage... | Credit tracking |
+| `client.policies` | upload, list, get, get_summary, set_active... | Policy management |
+| `client.users` | list, list_projects, get_projects | User & project lookups |
+
+## Async Usage
+
+```python
+from opus_aaico import AsyncOpusClient
+
+async with AsyncOpusClient(api_key="sk-...") as client:
+    result = await client.workflows.run("wf-123", payload={...})
+```
+
+## Error Handling
+
+```python
+from opus_aaico import OpusClient, NotFoundError, RateLimitError, OpusError
+
+try:
+    result = client.workflows.run("wf-123", payload={...})
+except NotFoundError:
+    print("Workflow not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except OpusError as e:
+    print(f"API error: {e.message}")
+```
+
+## Configuration
+
+```python
+client = OpusClient(
+    api_key="sk-...",
+    workspace_id="ws-...",
+    base_url="https://operator.opus.com",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx
+- pydantic v2
+
+## License
+
+MIT

opus_aaico-0.1.0/README.md

@@ -0,0 +1,103 @@
+# opus-aaico
+
+Official Python SDK for the [OPUS](https://opus.com) workflow automation platform.
+
+Features:
+- Full coverage of all OPUS API endpoints (64 endpoints)
+- Sync and async clients
+- Type-safe with Pydantic models
+- Automatic retry with exponential backoff
+- High-level `workflows.run()` orchestrator
+
+## Installation
+
+```
+pip install opus-aaico
+```
+
+## Quick Start
+
+```python
+from opus_aaico import OpusClient
+
+client = OpusClient(api_key="your-api-key")
+
+# Run a workflow end-to-end (initiate -> execute -> poll -> results)
+result = client.workflows.run(
+    workflow_id="wf-123",
+    payload={"query": {"value": "Analyze this", "type": "str"}},
+)
+print(result.outputs)
+```
+
+## Authentication
+
+```python
+# Pass directly
+client = OpusClient(api_key="sk-...")
+
+# Or set environment variables
+# OPUS_API_KEY=sk-...
+# OPUS_WORKSPACE_ID=ws-...  (optional)
+# OPUS_BASE_URL=https://custom.opus.com  (optional)
+client = OpusClient()
+```
+
+## Resources
+
+| Resource | Methods | Description |
+|----------|---------|-------------|
+| `client.workflows` | get, list, list_public, generate, run, share, send_email... | Workflow management + orchestration |
+| `client.jobs` | initiate, execute, get_status, get_results, poll, search... | Job lifecycle management |
+| `client.files` | upload, download, search, generate, multipart_upload... | File operations |
+| `client.reviews` | initiate, list, get, pick, submit_result, submit_output... | Human review management |
+| `client.api_keys` | create, list, rotate, revoke, delete... | API key management |
+| `client.credits` | get_balance, get_usage, record_usage... | Credit tracking |
+| `client.policies` | upload, list, get, get_summary, set_active... | Policy management |
+| `client.users` | list, list_projects, get_projects | User & project lookups |
+
+## Async Usage
+
+```python
+from opus_aaico import AsyncOpusClient
+
+async with AsyncOpusClient(api_key="sk-...") as client:
+    result = await client.workflows.run("wf-123", payload={...})
+```
+
+## Error Handling
+
+```python
+from opus_aaico import OpusClient, NotFoundError, RateLimitError, OpusError
+
+try:
+    result = client.workflows.run("wf-123", payload={...})
+except NotFoundError:
+    print("Workflow not found")
+except RateLimitError as e:
+    print(f"Rate limited, retry after {e.retry_after}s")
+except OpusError as e:
+    print(f"API error: {e.message}")
+```
+
+## Configuration
+
+```python
+client = OpusClient(
+    api_key="sk-...",
+    workspace_id="ws-...",
+    base_url="https://operator.opus.com",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- httpx
+- pydantic v2
+
+## License
+
+MIT

opus_aaico-0.1.0/examples/async_polling.py

@@ -0,0 +1,26 @@
+"""Poll multiple jobs concurrently with async client."""
+import asyncio
+
+from opus_aaico import AsyncOpusClient
+
+
+async def main():
+    async with AsyncOpusClient(api_key="your-api-key-here") as client:
+        # Run multiple workflows concurrently
+        tasks = [
+            client.workflows.run(
+                workflow_id="your-workflow-id",
+                payload={"query": {"value": f"Task {i}", "type": "str"}},
+                title=f"Concurrent Job {i}",
+            )
+            for i in range(5)
+        ]
+
+        results = await asyncio.gather(*tasks)
+
+        for i, result in enumerate(results):
+            print(f"Job {i}: {result.status} in {result.execution_time:.1f}s")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

opus_aaico-0.1.0/examples/error_handling.py

@@ -0,0 +1,37 @@
+"""Demonstrate error handling patterns."""
+from opus_aaico import (
+    AuthenticationError,
+    NotFoundError,
+    OpusClient,
+    OpusError,
+    RateLimitError,
+)
+
+# Bad API key
+try:
+    client = OpusClient(api_key="invalid-key")
+    client.workflows.get("wf-123")
+except AuthenticationError:
+    print("Invalid API key")
+
+# Workflow not found
+try:
+    client = OpusClient(api_key="your-api-key-here")
+    client.workflows.get("nonexistent-workflow")
+except NotFoundError:
+    print("Workflow not found")
+
+# Rate limiting
+try:
+    client = OpusClient(api_key="your-api-key-here")
+    # SDK automatically retries on 429, but if retries exhausted:
+    client.jobs.search()
+except RateLimitError as e:
+    print(f"Rate limited. Retry after: {e.retry_after}s")
+
+# Catch-all for any OPUS error
+try:
+    client = OpusClient(api_key="your-api-key-here")
+    client.workflows.run("wf-123", payload={})
+except OpusError as e:
+    print(f"OPUS error: {e.message} (status={e.status_code})")

opus_aaico-0.1.0/examples/file_upload.py

@@ -0,0 +1,18 @@
+"""Upload a file and use it in a workflow."""
+from opus_aaico import OpusClient
+
+client = OpusClient(api_key="your-api-key-here")
+
+# Upload a file (handles presigned URL flow automatically)
+file_url = client.files.upload("./report.pdf")
+print(f"Uploaded: {file_url}")
+
+# Use the uploaded file in a workflow
+result = client.workflows.run(
+    workflow_id="your-workflow-id",
+    payload={
+        "document": {"value": file_url, "type": "file"},
+        "query": {"value": "Summarize this report", "type": "str"},
+    },
+)
+print(f"Result: {result.outputs}")

opus_aaico-0.1.0/examples/quickstart.py

@@ -0,0 +1,11 @@
+"""Quickstart -- get workflow details in 4 lines."""
+from opus_aaico import OpusClient
+
+client = OpusClient(api_key="your-api-key-here")
+
+# Get workflow details
+workflow = client.workflows.get("your-workflow-id")
+print(f"Workflow: {workflow.name}")
+print(f"Active: {workflow.active}")
+if workflow.job_payload_schema:
+    print(f"Expected inputs: {list(workflow.job_payload_schema.keys())}")

opus_aaico-0.1.0/examples/run_workflow.py

@@ -0,0 +1,21 @@
+"""Run a workflow end-to-end with the high-level run() method."""
+from opus_aaico import OpusClient
+
+client = OpusClient(api_key="your-api-key-here")
+
+# The run() method handles: initiate -> execute -> poll -> results
+result = client.workflows.run(
+    workflow_id="your-workflow-id",
+    payload={
+        "query": {"value": "Analyze this document", "type": "str"},
+    },
+    title="My Analysis Job",
+    poll_interval=2.0,  # Check every 2 seconds
+    timeout=300,  # Wait up to 5 minutes
+)
+
+print(f"Status: {result.status}")
+print(f"Job ID: {result.job_id}")
+print(f"Execution time: {result.execution_time:.1f}s")
+if result.outputs:
+    print(f"Outputs: {result.outputs}")

opus_aaico-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opus-aaico"
+version = "0.1.0"
+description = "Official Python SDK for the OPUS workflow automation platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "AAICO", email = "support@aaico.com" },
+]
+keywords = ["opus", "workflow", "automation", "ai", "sdk", "aaico"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24,<1",
+    "pydantic>=2.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "pytest-httpx>=0.21",
+    "ruff>=0.1",
+    "mypy>=1.0",
+    "build>=1.0",
+]
+
+[project.urls]
+Homepage = "https://opus.com"
+Documentation = "https://docs.opus.com/sdk/python"
+Repository = "https://github.com/aaico/opus-aaico-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opus_aaico"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

opus_aaico-0.1.0/src/opus_aaico/__init__.py

@@ -0,0 +1,32 @@
+"""Official Python SDK for the OPUS workflow automation platform."""
+
+__version__ = "0.1.0"
+
+from opus_aaico._async import AsyncOpusClient
+from opus_aaico._exceptions import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    NotFoundError,
+    OpusError,
+    PermissionDeniedError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+from opus_aaico._sync import OpusClient
+
+__all__ = [
+    "__version__",
+    "OpusClient",
+    "AsyncOpusClient",
+    "OpusError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "APIError",
+    "TimeoutError",
+    "ConnectionError",
+]

opus_aaico-0.1.0/src/opus_aaico/_async.py

@@ -0,0 +1,44 @@
+"""Asynchronous OPUS client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opus_aaico._client import AsyncHTTPClient
+from opus_aaico.resources.api_keys import AsyncApiKeys
+from opus_aaico.resources.credits import AsyncCredits
+from opus_aaico.resources.files import AsyncFiles
+from opus_aaico.resources.jobs import AsyncJobs
+from opus_aaico.resources.policies import AsyncPolicies
+from opus_aaico.resources.reviews import AsyncReviews
+from opus_aaico.resources.users import AsyncUsers
+from opus_aaico.resources.workflows import AsyncWorkflows
+
+
+class AsyncOpusClient:
+    """Asynchronous client for the OPUS API.
+
+    Usage:
+        async with AsyncOpusClient(api_key="sk-...") as client:
+            result = await client.workflows.run("wf-123", payload={...})
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._http = AsyncHTTPClient(**kwargs)
+        self.jobs = AsyncJobs(self._http)
+        self.workflows = AsyncWorkflows(self._http, self.jobs)
+        self.files = AsyncFiles(self._http)
+        self.reviews = AsyncReviews(self._http)
+        self.api_keys = AsyncApiKeys(self._http)
+        self.credits = AsyncCredits(self._http)
+        self.policies = AsyncPolicies(self._http)
+        self.users = AsyncUsers(self._http)
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncOpusClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()