# Opal Tools SDK for Python
This SDK simplifies the creation of tools services compatible with the Opal Tools Management Service.
## Features
- Easy definition of tool functions with decorators
- Automatic generation of discovery endpoints
- Parameter validation and type checking
- Authentication helpers
- FastAPI integration
## Installation
```bash
pip install optimizely-opal.opal-tools-sdk
```
Note: While the package is installed as `optimizely-opal.opal-tools-sdk`, you'll still import it in your code as `opal_tools_sdk`:
```python
# Import using the package name
from opal_tools_sdk import ToolsService, tool
```
## Usage
```python
from opal_tools_sdk import ToolsService, tool
from pydantic import BaseModel
from fastapi import FastAPI
app = FastAPI()
tools_service = ToolsService(app)
class WeatherParameters(BaseModel):
location: str
units: str = "metric"
@tool("get_weather", "Gets current weather for a location")
async def get_weather(parameters: WeatherParameters):
# Implementation...
return {"temperature": 22, "condition": "sunny"}
# Discovery endpoint is automatically created at /discovery
```
## Authentication
The SDK provides two ways to require authentication for your tools:
### 1. Using the `@requires_auth` decorator
```python
from opal_tools_sdk import ToolsService, tool
from opal_tools_sdk.auth import requires_auth
from pydantic import BaseModel
from fastapi import FastAPI
app = FastAPI()
tools_service = ToolsService(app)
class CalendarParameters(BaseModel):
date: str
timezone: str = "UTC"
# Single authentication requirement
@requires_auth(provider="google", scope_bundle="calendar", required=True)
@tool("get_calendar_events", "Gets calendar events for a date")
async def get_calendar_events(parameters: CalendarParameters, auth_data=None):
# The auth_data parameter contains authentication information
token = auth_data.get("credentials", {}).get("token", "")
# Use the token to make authenticated requests
# ...
return {"events": ["Meeting at 10:00", "Lunch at 12:00"]}
# Multiple authentication requirements (tool can work with either provider)
@requires_auth(provider="google", scope_bundle="calendar", required=True)
@requires_auth(provider="microsoft", scope_bundle="outlook", required=True)
@tool("get_calendar_availability", "Check calendar availability")
async def get_calendar_availability(parameters: CalendarParameters, auth_data=None):
provider = auth_data.get("provider", "")
token = auth_data.get("credentials", {}).get("token", "")
if provider == "google":
# Use Google Calendar API
pass
elif provider == "microsoft":
# Use Microsoft Outlook API
pass
return {"available": True, "provider_used": provider}
```
### 2. Specifying auth requirements in the `@tool` decorator
```python
@tool(
"get_email",
"Gets emails from the user's inbox",
auth_requirements=[
{"provider": "google", "scope_bundle": "gmail", "required": True}
]
)
async def get_email(parameters: EmailParameters, auth_data=None):
# Implementation...
return {"emails": ["Email 1", "Email 2"]}
```
## Documentation
See full documentation for more examples and configuration options.
Raw data
{
"_id": null,
"home_page": "https://github.com/optimizely/opal-tools-sdk",
"name": "optimizely-opal.opal-tools-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "opal, tools, sdk, ai, llm",
"author": "Optimizely",
"author_email": "Optimizely <opal-team@optimizely.com>",
"download_url": "https://files.pythonhosted.org/packages/da/4a/868ee0e16ca3f5af77a37dfb42b62797a29005ee25bfa93db0735ae3f6a3/optimizely_opal_opal_tools_sdk-0.1.4.dev0.tar.gz",
"platform": null,
"description": "# Opal Tools SDK for Python\n\nThis SDK simplifies the creation of tools services compatible with the Opal Tools Management Service.\n\n## Features\n\n- Easy definition of tool functions with decorators\n- Automatic generation of discovery endpoints\n- Parameter validation and type checking\n- Authentication helpers\n- FastAPI integration\n\n## Installation\n\n```bash\npip install optimizely-opal.opal-tools-sdk\n```\n\nNote: While the package is installed as `optimizely-opal.opal-tools-sdk`, you'll still import it in your code as `opal_tools_sdk`:\n\n```python\n# Import using the package name\nfrom opal_tools_sdk import ToolsService, tool\n```\n\n## Usage\n\n```python\nfrom opal_tools_sdk import ToolsService, tool\nfrom pydantic import BaseModel\nfrom fastapi import FastAPI\n\napp = FastAPI()\ntools_service = ToolsService(app)\n\nclass WeatherParameters(BaseModel):\n location: str\n units: str = \"metric\"\n\n@tool(\"get_weather\", \"Gets current weather for a location\")\nasync def get_weather(parameters: WeatherParameters):\n # Implementation...\n return {\"temperature\": 22, \"condition\": \"sunny\"}\n\n# Discovery endpoint is automatically created at /discovery\n```\n\n## Authentication\n\nThe SDK provides two ways to require authentication for your tools:\n\n### 1. Using the `@requires_auth` decorator\n\n```python\nfrom opal_tools_sdk import ToolsService, tool\nfrom opal_tools_sdk.auth import requires_auth\nfrom pydantic import BaseModel\nfrom fastapi import FastAPI\n\napp = FastAPI()\ntools_service = ToolsService(app)\n\nclass CalendarParameters(BaseModel):\n date: str\n timezone: str = \"UTC\"\n\n# Single authentication requirement\n@requires_auth(provider=\"google\", scope_bundle=\"calendar\", required=True)\n@tool(\"get_calendar_events\", \"Gets calendar events for a date\")\nasync def get_calendar_events(parameters: CalendarParameters, auth_data=None):\n # The auth_data parameter contains authentication information\n token = auth_data.get(\"credentials\", {}).get(\"token\", \"\")\n\n # Use the token to make authenticated requests\n # ...\n\n return {\"events\": [\"Meeting at 10:00\", \"Lunch at 12:00\"]}\n\n# Multiple authentication requirements (tool can work with either provider)\n@requires_auth(provider=\"google\", scope_bundle=\"calendar\", required=True)\n@requires_auth(provider=\"microsoft\", scope_bundle=\"outlook\", required=True)\n@tool(\"get_calendar_availability\", \"Check calendar availability\")\nasync def get_calendar_availability(parameters: CalendarParameters, auth_data=None):\n provider = auth_data.get(\"provider\", \"\")\n token = auth_data.get(\"credentials\", {}).get(\"token\", \"\")\n\n if provider == \"google\":\n # Use Google Calendar API\n pass\n elif provider == \"microsoft\":\n # Use Microsoft Outlook API\n pass\n\n return {\"available\": True, \"provider_used\": provider}\n```\n\n### 2. Specifying auth requirements in the `@tool` decorator\n\n```python\n@tool(\n \"get_email\",\n \"Gets emails from the user's inbox\",\n auth_requirements=[\n {\"provider\": \"google\", \"scope_bundle\": \"gmail\", \"required\": True}\n ]\n)\nasync def get_email(parameters: EmailParameters, auth_data=None):\n # Implementation...\n return {\"emails\": [\"Email 1\", \"Email 2\"]}\n```\n\n## Documentation\n\nSee full documentation for more examples and configuration options.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SDK for creating Opal-compatible tools services",
"version": "0.1.4.dev0",
"project_urls": {
"Bug Tracker": "https://github.com/optimizely/opal-tools-sdk/issues",
"Homepage": "https://github.com/optimizely/opal-tools-sdk"
},
"split_keywords": [
"opal",
" tools",
" sdk",
" ai",
" llm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e44fcd8b2fac4ae36493b97145121d801303e25f852c50e6e434ac694d3d6853",
"md5": "9e022286d97fc3e39ff1b62ff9b5b4fc",
"sha256": "d7d621e70724b0ed7818e0d09fa7ad68567d2543548e82f233230e4bdc4b7e84"
},
"downloads": -1,
"filename": "optimizely_opal_opal_tools_sdk-0.1.4.dev0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e022286d97fc3e39ff1b62ff9b5b4fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9601,
"upload_time": "2025-07-23T17:22:23",
"upload_time_iso_8601": "2025-07-23T17:22:23.188828Z",
"url": "https://files.pythonhosted.org/packages/e4/4f/cd8b2fac4ae36493b97145121d801303e25f852c50e6e434ac694d3d6853/optimizely_opal_opal_tools_sdk-0.1.4.dev0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "da4a868ee0e16ca3f5af77a37dfb42b62797a29005ee25bfa93db0735ae3f6a3",
"md5": "6605d1612611edaeb48bebe65f6da445",
"sha256": "0f25236cc5d7d3be9a4bc1d0beda9455f6078b2693b4da568c7fc1c6f43c1624"
},
"downloads": -1,
"filename": "optimizely_opal_opal_tools_sdk-0.1.4.dev0.tar.gz",
"has_sig": false,
"md5_digest": "6605d1612611edaeb48bebe65f6da445",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9026,
"upload_time": "2025-07-23T17:22:25",
"upload_time_iso_8601": "2025-07-23T17:22:25.033342Z",
"url": "https://files.pythonhosted.org/packages/da/4a/868ee0e16ca3f5af77a37dfb42b62797a29005ee25bfa93db0735ae3f6a3/optimizely_opal_opal_tools_sdk-0.1.4.dev0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 17:22:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "optimizely",
"github_project": "opal-tools-sdk",
"github_not_found": true,
"lcname": "optimizely-opal.opal-tools-sdk"
}