# PromptQL Natural Language API SDK for Python
A Python SDK for interacting with the [PromptQL Natural Language API](https://hasura.io/docs/promptql/promptql-apis/natural-language-api/).
## Installation
```bash
pip install promptql-api-sdk
```
Or with Poetry:
```bash
poetry add promptql-api-sdk
```
## Features
- Full support for the PromptQL Natural Language API (v1 and v2)
- Type-safe interface with Pydantic models
- Support for streaming responses
- Conversation management
- Support for all LLM providers (Hasura, Anthropic, OpenAI)
- Support for build-based configuration (v2 API)
## Quick Start
### v2 API (Recommended)
The v2 API uses build-based configuration and is the recommended approach:
```python
from promptql_api_sdk import PromptQLClient
# Initialize the client with build version
client = PromptQLClient(
api_key="your-promptql-api-key",
build_version="your-build-version", # or use build_id=UUID("your-build-id")
timezone="America/Los_Angeles",
)
# Send a simple query
response = client.query("What is the average temperature in San Francisco?")
print(response.assistant_actions[0].message)
# Use streaming for real-time responses
for chunk in client.query("Tell me about the weather in New York", stream=True):
if hasattr(chunk, "message") and chunk.message:
print(chunk.message, end="", flush=True)
```
**Note:** To use applied build, do not specify `build_version` or `build_id`.
```python
client = PromptQLClient(
api_key="your-promptql-api-key",
timezone="America/Los_Angeles",
)
```
### v1 API (Legacy)
The v1 API requires DDN `/v1/sql` URL and explicit LLM provider configuration:
```python
from promptql_api_sdk import PromptQLClient
from promptql_api_sdk.types.models import HasuraLLMProvider
# Initialize the client
client = PromptQLClient(
api_key="your-promptql-api-key",
ddn_url="your-ddn-url/v1/sql",
llm_provider=HasuraLLMProvider(), # Required for v1 API
timezone="America/Los_Angeles",
)
# Send a simple query
response = client.query("What is the average temperature in San Francisco?")
print(response.assistant_actions[0].message)
```
## Private DDN
If you are using a private DDN, you need to provide the base URL for the PromptQL API:
```python
client = PromptQLClient(
api_key="your-promptql-api-key",
build_version="your-build-version",
timezone="America/Los_Angeles",
api_base_url="https://promptql.fqdn.hasura.app/api",
)
```
**Note:** The `api_base_url` should not include the `/query` endpoint.
For more details refer to the [PromptQL API Endpoint documentation](https://promptql.io/docs/promptql-apis/natural-language-api/#query-endpoint).
## Conversation Management
The SDK provides a `Conversation` class to help manage multi-turn conversations:
```python
# Create a conversation
conversation = client.create_conversation(
system_instructions="You are a helpful assistant that provides weather information."
# Note: system_instructions are ignored in v2 API as they come from build's PromptQL config
)
# Send messages in the conversation
response = conversation.send_message("What's the weather like in London?")
print(response.message)
# Send a follow-up message
response = conversation.send_message("How about tomorrow?")
print(response.message)
# Get all artifacts created during the conversation
artifacts = conversation.get_artifacts()
```
## LLM Provider Configuration (v1 API only)
The SDK supports multiple LLM providers for v1 API:
```python
from promptql_api_sdk.types.models import HasuraLLMProvider, AnthropicLLMProvider, OpenAILLMProvider
# Hasura (default)
hasura_provider = HasuraLLMProvider()
# Anthropic
anthropic_provider = AnthropicLLMProvider(api_key="your-anthropic-api-key")
# OpenAI
openai_provider = OpenAILLMProvider(api_key="your-openai-api-key")
# Use with the client (v1 API only)
client = PromptQLClient(
api_key="your-promptql-api-key",
ddn_url="your-ddn-url/v1/sql",
llm_provider=anthropic_provider,
)
```
> **Note**: In v2 API, LLM configuration is managed through the DDN build's PromptQL settings.
## API Version Differences
### v2 API (Recommended)
- Uses build-based configuration (`build_version` or `build_id`) (optional, uses applied build if not specified)
- LLM configuration and system instructions come from build's PromptQL config
### v1 API (Legacy)
- Uses direct DDN `/v1/sql` URL
- Requires explicit LLM provider configuration
- System instructions specified in requests
## Error Handling
```python
from promptql_api_sdk import PromptQLClient
from promptql_api_sdk.exceptions import PromptQLAPIError
client = PromptQLClient(...)
try:
response = client.query("What is the weather like?")
except PromptQLAPIError as e:
print(f"API Error: {e}")
```
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/hasura/promptql-python-sdk",
"name": "promptql-api-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "promptql, api, sdk, hasura, llm, ai",
"author": "Hasura Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ba/0e/f1e7a27cc4de11c861b3ff05c080be4d329ad0fc5334355a6788389edc8f/promptql_api_sdk-0.2.0.tar.gz",
"platform": null,
"description": "# PromptQL Natural Language API SDK for Python\n\nA Python SDK for interacting with the [PromptQL Natural Language API](https://hasura.io/docs/promptql/promptql-apis/natural-language-api/).\n\n## Installation\n\n```bash\npip install promptql-api-sdk\n```\n\nOr with Poetry:\n\n```bash\npoetry add promptql-api-sdk\n```\n\n## Features\n\n- Full support for the PromptQL Natural Language API (v1 and v2)\n- Type-safe interface with Pydantic models\n- Support for streaming responses\n- Conversation management\n- Support for all LLM providers (Hasura, Anthropic, OpenAI)\n- Support for build-based configuration (v2 API)\n\n## Quick Start\n\n### v2 API (Recommended)\n\nThe v2 API uses build-based configuration and is the recommended approach:\n\n```python\nfrom promptql_api_sdk import PromptQLClient\n\n# Initialize the client with build version\nclient = PromptQLClient(\n api_key=\"your-promptql-api-key\",\n build_version=\"your-build-version\", # or use build_id=UUID(\"your-build-id\")\n timezone=\"America/Los_Angeles\",\n)\n\n# Send a simple query\nresponse = client.query(\"What is the average temperature in San Francisco?\")\nprint(response.assistant_actions[0].message)\n\n# Use streaming for real-time responses\nfor chunk in client.query(\"Tell me about the weather in New York\", stream=True):\n if hasattr(chunk, \"message\") and chunk.message:\n print(chunk.message, end=\"\", flush=True)\n```\n\n**Note:** To use applied build, do not specify `build_version` or `build_id`.\n\n```python\nclient = PromptQLClient(\n api_key=\"your-promptql-api-key\",\n timezone=\"America/Los_Angeles\",\n)\n```\n\n### v1 API (Legacy)\n\nThe v1 API requires DDN `/v1/sql` URL and explicit LLM provider configuration:\n\n```python\nfrom promptql_api_sdk import PromptQLClient\nfrom promptql_api_sdk.types.models import HasuraLLMProvider\n\n# Initialize the client\nclient = PromptQLClient(\n api_key=\"your-promptql-api-key\",\n ddn_url=\"your-ddn-url/v1/sql\",\n llm_provider=HasuraLLMProvider(), # Required for v1 API\n timezone=\"America/Los_Angeles\",\n)\n\n# Send a simple query\nresponse = client.query(\"What is the average temperature in San Francisco?\")\nprint(response.assistant_actions[0].message)\n```\n\n## Private DDN\n\nIf you are using a private DDN, you need to provide the base URL for the PromptQL API:\n\n```python\nclient = PromptQLClient(\n api_key=\"your-promptql-api-key\",\n build_version=\"your-build-version\",\n timezone=\"America/Los_Angeles\",\n api_base_url=\"https://promptql.fqdn.hasura.app/api\",\n)\n```\n\n**Note:** The `api_base_url` should not include the `/query` endpoint.\n\nFor more details refer to the [PromptQL API Endpoint documentation](https://promptql.io/docs/promptql-apis/natural-language-api/#query-endpoint).\n\n## Conversation Management\n\nThe SDK provides a `Conversation` class to help manage multi-turn conversations:\n\n```python\n# Create a conversation\nconversation = client.create_conversation(\n system_instructions=\"You are a helpful assistant that provides weather information.\"\n # Note: system_instructions are ignored in v2 API as they come from build's PromptQL config\n)\n\n# Send messages in the conversation\nresponse = conversation.send_message(\"What's the weather like in London?\")\nprint(response.message)\n\n# Send a follow-up message\nresponse = conversation.send_message(\"How about tomorrow?\")\nprint(response.message)\n\n# Get all artifacts created during the conversation\nartifacts = conversation.get_artifacts()\n```\n\n## LLM Provider Configuration (v1 API only)\n\nThe SDK supports multiple LLM providers for v1 API:\n\n```python\nfrom promptql_api_sdk.types.models import HasuraLLMProvider, AnthropicLLMProvider, OpenAILLMProvider\n\n# Hasura (default)\nhasura_provider = HasuraLLMProvider()\n\n# Anthropic\nanthropic_provider = AnthropicLLMProvider(api_key=\"your-anthropic-api-key\")\n\n# OpenAI\nopenai_provider = OpenAILLMProvider(api_key=\"your-openai-api-key\")\n\n# Use with the client (v1 API only)\nclient = PromptQLClient(\n api_key=\"your-promptql-api-key\",\n ddn_url=\"your-ddn-url/v1/sql\",\n llm_provider=anthropic_provider,\n)\n```\n\n> **Note**: In v2 API, LLM configuration is managed through the DDN build's PromptQL settings.\n\n## API Version Differences\n\n### v2 API (Recommended)\n- Uses build-based configuration (`build_version` or `build_id`) (optional, uses applied build if not specified)\n- LLM configuration and system instructions come from build's PromptQL config\n\n### v1 API (Legacy)\n- Uses direct DDN `/v1/sql` URL\n- Requires explicit LLM provider configuration\n- System instructions specified in requests\n\n## Error Handling\n\n```python\nfrom promptql_api_sdk import PromptQLClient\nfrom promptql_api_sdk.exceptions import PromptQLAPIError\n\nclient = PromptQLClient(...)\n\ntry:\n response = client.query(\"What is the weather like?\")\nexcept PromptQLAPIError as e:\n print(f\"API Error: {e}\")\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for PromptQL Natural Language API",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://hasura.io/docs/promptql/promptql-apis/natural-language-api/",
"Homepage": "https://github.com/hasura/promptql-python-sdk",
"Repository": "https://github.com/hasura/promptql-python-sdk"
},
"split_keywords": [
"promptql",
" api",
" sdk",
" hasura",
" llm",
" ai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d55ee3e8bf4e0300d333e06e8cfa499adc9e049391477528688ac4788518105",
"md5": "4425cd30acf952d0623ea05167d23734",
"sha256": "713163a2d6185e0baf50afacf3a3c46911f7ff7158e3213832f60ec2de0dee07"
},
"downloads": -1,
"filename": "promptql_api_sdk-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4425cd30acf952d0623ea05167d23734",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10774,
"upload_time": "2025-07-21T15:58:46",
"upload_time_iso_8601": "2025-07-21T15:58:46.108200Z",
"url": "https://files.pythonhosted.org/packages/0d/55/ee3e8bf4e0300d333e06e8cfa499adc9e049391477528688ac4788518105/promptql_api_sdk-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba0ef1e7a27cc4de11c861b3ff05c080be4d329ad0fc5334355a6788389edc8f",
"md5": "faa420755a759f4de7125ef839f33786",
"sha256": "3362ce324268a0f0ba48105e36925490c854cfef34ad6b62bc5e74ea7182a7e4"
},
"downloads": -1,
"filename": "promptql_api_sdk-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "faa420755a759f4de7125ef839f33786",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9516,
"upload_time": "2025-07-21T15:58:47",
"upload_time_iso_8601": "2025-07-21T15:58:47.516328Z",
"url": "https://files.pythonhosted.org/packages/ba/0e/f1e7a27cc4de11c861b3ff05c080be4d329ad0fc5334355a6788389edc8f/promptql_api_sdk-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 15:58:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hasura",
"github_project": "promptql-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "promptql-api-sdk"
}
JSON
