airia 0.1.9__tar.gz → 0.1.11__tar.gz

{airia-0.1.9 → airia-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airia
-Version: 0.1.9
+Version: 0.1.11
 Summary: Python SDK for Airia API
 Author-email: Airia LLC <support@airia.com>
 License: MIT
@@ -43,7 +43,9 @@ Airia Python API Library that provides a clean and intuitive interface to intera
 - **Gateway Support**: Seamlessly integrate with OpenAI and Anthropic services through Airia gateways
 - **Error Handling**: Comprehensive error handling with custom exceptions
 - **Logging**: Built-in configurable logging with correlation ID support for request tracing
-- **API Key Management**: Flexible API key configuration via parameters or environment variables
+- **Flexible Authentication**: Support for both API keys and bearer tokens with flexible configuration
+- **API Key Management**: API key configuration via parameters or environment variables
+- **Bearer Token Support**: Bearer token authentication for ephemeral, short-lived credentials
 
 ## Installation
 
@@ -181,17 +183,38 @@ This will create both wheel and source distribution in the `dist/` directory.
 ```python
 from airia import AiriaClient
 
+# API Key Authentication
 client = AiriaClient(
     base_url="https://api.airia.ai",        # Default: "https://api.airia.ai"
-    api_key=None,                  # Or set AIRIA_API_KEY environment variable
-    timeout=30.0,                            # Request timeout in seconds (default: 30.0)
-    log_requests=False,                       # Enable request/response logging (default: False)
-    custom_logger=None                       # Use custom logger (default: None - uses built-in)
+    api_key=None,                           # Or set AIRIA_API_KEY environment variable
+    timeout=30.0,                           # Request timeout in seconds (default: 30.0)
+    log_requests=False,                     # Enable request/response logging (default: False)
+    custom_logger=None                      # Use custom logger (default: None - uses built-in)
+)
+
+# Bearer Token Authentication
+client = AiriaClient(
+    base_url="https://api.airia.ai",        # Default: "https://api.airia.ai"
+    bearer_token="your_bearer_token",       # Must be provided explicitly (no env var fallback)
+    timeout=30.0,                           # Request timeout in seconds (default: 30.0)
+    log_requests=False,                     # Enable request/response logging (default: False)
+    custom_logger=None                      # Use custom logger (default: None - uses built-in)
+)
+
+# Convenience method for bearer token
+client = AiriaClient.with_bearer_token(
+    bearer_token="your_bearer_token",
+    base_url="https://api.airia.ai",        # Optional, uses default if not provided
+    timeout=30.0,                           # Optional, uses default if not provided
+    log_requests=False,                     # Optional, uses default if not provided
+    custom_logger=None                      # Optional, uses default if not provided
 )
 ```
 
 ### Synchronous Usage
 
+#### With API Key
+
 ```python
 from airia import AiriaClient
 
@@ -207,6 +230,23 @@ response = client.execute_pipeline(
 print(response.result)
 ```
 
+#### With Bearer Token
+
+```python
+from airia import AiriaClient
+
+# Initialize client with bearer token
+client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
+
+# Execute a pipeline
+response = client.execute_pipeline(
+    pipeline_id="your_pipeline_id",
+    user_input="Tell me about quantum computing"
+)
+
+print(response.result)
+```
+
 #### Synchronous Streaming
 
 ```python
@@ -214,6 +254,7 @@ from airia import AiriaClient
 
 # Initialize client (API key can be passed directly or via AIRIA_API_KEY environment variable)
 client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 # Execute a pipeline
 response = client.execute_pipeline(
@@ -228,6 +269,8 @@ for c in response.stream:
 
 ### Asynchronous Usage
 
+#### With API Key
+
 ```python
 import asyncio
 from airia import AiriaAsyncClient
@@ -243,6 +286,23 @@ async def main():
 asyncio.run(main())
 ```
 
+#### With Bearer Token
+
+```python
+import asyncio
+from airia import AiriaAsyncClient
+
+async def main():
+    client = AiriaAsyncClient.with_bearer_token(bearer_token="your_bearer_token")
+    response = await client.execute_pipeline(
+        pipeline_id="your_pipeline_id",
+        user_input="Tell me about quantum computing"
+    )
+    print(response.result)
+
+asyncio.run(main())
+```
+
 #### Asynchronous Streaming
 
 ```python
@@ -251,6 +311,7 @@ from airia import AiriaAsyncClient
 
 async def main():
     client = AiriaAsyncClient(api_key="your_api_key")
+    # Or with bearer token: client = AiriaAsyncClient.with_bearer_token(bearer_token="your_bearer_token")
     response = await client.execute_pipeline(
         pipeline_id="your_pipeline_id",
         user_input="Tell me about quantum computing",
@@ -268,7 +329,7 @@ When using streaming mode (`async_output=True`), the API returns Server-Sent Eve
 
 ### Available Message Types
 
-The streaming response includes various message types defined in `airia.types`. Here are the key ones:
+The streaming response includes various message types defined in `airia.types.sse`. Here are the key ones:
 
 - `AgentModelStreamFragmentMessage` - Contains actual LLM output chunks
 - `AgentModelStreamStartMessage` - Indicates LLM streaming has started
@@ -320,6 +381,7 @@ from airia import AiriaClient
 from airia.types import AgentModelStreamFragmentMessage
 
 client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 response = client.execute_pipeline(
     pipeline_id="your_pipeline_id",
@@ -343,6 +405,7 @@ You can retrieve detailed configuration information about a pipeline using the `
 from airia import AiriaClient
 
 client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 # Get pipeline configuration
 config = client.get_pipeline_config(pipeline_id="your_pipeline_id")
@@ -351,10 +414,117 @@ config = client.get_pipeline_config(pipeline_id="your_pipeline_id")
 print(f"Pipeline Name: {config.agent.name}")
 ```
 
+## Conversation Management
+
+You can create and manage conversations using the `create_conversation` method. Conversations allow you to organize and persist interactions within the Airia platform.
+
+### Creating Conversations
+
+#### Synchronous Usage
+
+```python
+from airia import AiriaClient
+
+client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
+
+# Create a basic conversation
+conversation = client.create_conversation(
+    user_id="user_123"
+)
+print(f"Created conversation: {conversation.conversation_id}")
+print(f"WebSocket URL: {conversation.websocket_url}")
+
+# Create a conversation with all options
+conversation = client.create_conversation(
+    user_id="user_123",
+    title="My Research Session",
+    deployment_id="deployment_456", 
+    data_source_files={"documents": ["doc1.pdf", "doc2.txt"]},
+    is_bookmarked=True
+)
+print(f"Created bookmarked conversation: {conversation.conversation_id}")
+```
+
+#### Asynchronous Usage
+
+```python
+import asyncio
+from airia import AiriaAsyncClient
+
+async def main():
+    client = AiriaAsyncClient(api_key="your_api_key")
+    # Or with bearer token: client = AiriaAsyncClient.with_bearer_token(bearer_token="your_bearer_token")
+    
+    # Create a basic conversation
+    conversation = await client.create_conversation(
+        user_id="user_123"
+    )
+    print(f"Created conversation: {conversation.conversation_id}")
+    
+    # Create a conversation with all options
+    conversation = await client.create_conversation(
+        user_id="user_123",
+        title="My Research Session",
+        deployment_id="deployment_456",
+        data_source_files={"documents": ["doc1.pdf", "doc2.txt"]},
+        is_bookmarked=True
+    )
+    print(f"Created bookmarked conversation: {conversation.conversation_id}")
+
+asyncio.run(main())
+```
+
+### Conversation Parameters
+
+- **user_id** (required): The unique identifier of the user creating the conversation
+- **title** (optional): A descriptive title for the conversation
+- **deployment_id** (optional): The unique identifier of the deployment to associate with the conversation
+- **data_source_files** (optional): Configuration for data source files to be associated with the conversation
+- **is_bookmarked** (optional): Whether the conversation should be bookmarked (defaults to False)
+- **correlation_id** (optional): A unique identifier for request tracing and logging
+
+### Response Fields
+
+The `create_conversation` method returns a `CreateConversationResponse` object containing:
+
+- **conversation_id**: The unique identifier of the created conversation
+- **user_id**: The user ID associated with the conversation
+- **websocket_url**: The WebSocket URL for real-time communication
+- **deployment_id**: The deployment ID associated with the conversation
+- **icon_id** and **icon_url**: Optional conversation icon information
+- **description**: Optional conversation description
+- **space_name**: Optional workspace or space name
+
+## Authentication Methods
+
+Airia supports two authentication methods:
+
+### API Keys
+- Can be passed as a parameter or via `AIRIA_API_KEY` environment variable
+- Support gateway functionality (OpenAI and Anthropic gateways)
+- Suitable for long-term, persistent authentication
+
+### Bearer Tokens
+- Must be provided explicitly (no environment variable fallback)
+- **Important**: Bearer tokens cannot be used with gateway functionality
+- Suitable for ephemeral, short-lived authentication scenarios
+- Ideal for temporary access or programmatic token generation
+
+```python
+# ✅ API key with gateway support
+client = AiriaClient.with_openai_gateway(api_key="your_api_key")
+
+# ❌ Bearer token with gateway - NOT SUPPORTED
+# client = AiriaClient.with_openai_gateway(bearer_token="token")  # This won't work
+```
+
 ## Gateway Usage
 
 Airia provides gateway capabilities for popular AI services like OpenAI and Anthropic, allowing you to use your Airia API key with these services.
 
+> **Note**: Gateway functionality requires API key authentication. Bearer tokens are not supported for gateway usage.
+
 ### OpenAI Gateway
 
 ```python
@@ -482,7 +652,11 @@ console_logger = configure_logging(
 The SDK uses custom exceptions to provide clear error messages:
 
 ```python
-from airia import AiriaAPIError
+from airia import AiriaAPIError, AiriaClient
+
+# Works with both API keys and bearer tokens
+client = AiriaClient(api_key="your_api_key")
+# Or: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 try:
     response = client.execute_pipeline(

{airia-0.1.9 → airia-0.1.11}/README.md

@@ -13,7 +13,9 @@ Airia Python API Library that provides a clean and intuitive interface to intera
 - **Gateway Support**: Seamlessly integrate with OpenAI and Anthropic services through Airia gateways
 - **Error Handling**: Comprehensive error handling with custom exceptions
 - **Logging**: Built-in configurable logging with correlation ID support for request tracing
-- **API Key Management**: Flexible API key configuration via parameters or environment variables
+- **Flexible Authentication**: Support for both API keys and bearer tokens with flexible configuration
+- **API Key Management**: API key configuration via parameters or environment variables
+- **Bearer Token Support**: Bearer token authentication for ephemeral, short-lived credentials
 
 ## Installation
 
@@ -151,17 +153,38 @@ This will create both wheel and source distribution in the `dist/` directory.
 ```python
 from airia import AiriaClient
 
+# API Key Authentication
 client = AiriaClient(
     base_url="https://api.airia.ai",        # Default: "https://api.airia.ai"
-    api_key=None,                  # Or set AIRIA_API_KEY environment variable
-    timeout=30.0,                            # Request timeout in seconds (default: 30.0)
-    log_requests=False,                       # Enable request/response logging (default: False)
-    custom_logger=None                       # Use custom logger (default: None - uses built-in)
+    api_key=None,                           # Or set AIRIA_API_KEY environment variable
+    timeout=30.0,                           # Request timeout in seconds (default: 30.0)
+    log_requests=False,                     # Enable request/response logging (default: False)
+    custom_logger=None                      # Use custom logger (default: None - uses built-in)
+)
+
+# Bearer Token Authentication
+client = AiriaClient(
+    base_url="https://api.airia.ai",        # Default: "https://api.airia.ai"
+    bearer_token="your_bearer_token",       # Must be provided explicitly (no env var fallback)
+    timeout=30.0,                           # Request timeout in seconds (default: 30.0)
+    log_requests=False,                     # Enable request/response logging (default: False)
+    custom_logger=None                      # Use custom logger (default: None - uses built-in)
+)
+
+# Convenience method for bearer token
+client = AiriaClient.with_bearer_token(
+    bearer_token="your_bearer_token",
+    base_url="https://api.airia.ai",        # Optional, uses default if not provided
+    timeout=30.0,                           # Optional, uses default if not provided
+    log_requests=False,                     # Optional, uses default if not provided
+    custom_logger=None                      # Optional, uses default if not provided
 )
 ```
 
 ### Synchronous Usage
 
+#### With API Key
+
 ```python
 from airia import AiriaClient
 
@@ -177,6 +200,23 @@ response = client.execute_pipeline(
 print(response.result)
 ```
 
+#### With Bearer Token
+
+```python
+from airia import AiriaClient
+
+# Initialize client with bearer token
+client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
+
+# Execute a pipeline
+response = client.execute_pipeline(
+    pipeline_id="your_pipeline_id",
+    user_input="Tell me about quantum computing"
+)
+
+print(response.result)
+```
+
 #### Synchronous Streaming
 
 ```python
@@ -184,6 +224,7 @@ from airia import AiriaClient
 
 # Initialize client (API key can be passed directly or via AIRIA_API_KEY environment variable)
 client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 # Execute a pipeline
 response = client.execute_pipeline(
@@ -198,6 +239,8 @@ for c in response.stream:
 
 ### Asynchronous Usage
 
+#### With API Key
+
 ```python
 import asyncio
 from airia import AiriaAsyncClient
@@ -213,6 +256,23 @@ async def main():
 asyncio.run(main())
 ```
 
+#### With Bearer Token
+
+```python
+import asyncio
+from airia import AiriaAsyncClient
+
+async def main():
+    client = AiriaAsyncClient.with_bearer_token(bearer_token="your_bearer_token")
+    response = await client.execute_pipeline(
+        pipeline_id="your_pipeline_id",
+        user_input="Tell me about quantum computing"
+    )
+    print(response.result)
+
+asyncio.run(main())
+```
+
 #### Asynchronous Streaming
 
 ```python
@@ -221,6 +281,7 @@ from airia import AiriaAsyncClient
 
 async def main():
     client = AiriaAsyncClient(api_key="your_api_key")
+    # Or with bearer token: client = AiriaAsyncClient.with_bearer_token(bearer_token="your_bearer_token")
     response = await client.execute_pipeline(
         pipeline_id="your_pipeline_id",
         user_input="Tell me about quantum computing",
@@ -238,7 +299,7 @@ When using streaming mode (`async_output=True`), the API returns Server-Sent Eve
 
 ### Available Message Types
 
-The streaming response includes various message types defined in `airia.types`. Here are the key ones:
+The streaming response includes various message types defined in `airia.types.sse`. Here are the key ones:
 
 - `AgentModelStreamFragmentMessage` - Contains actual LLM output chunks
 - `AgentModelStreamStartMessage` - Indicates LLM streaming has started
@@ -290,6 +351,7 @@ from airia import AiriaClient
 from airia.types import AgentModelStreamFragmentMessage
 
 client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 response = client.execute_pipeline(
     pipeline_id="your_pipeline_id",
@@ -313,6 +375,7 @@ You can retrieve detailed configuration information about a pipeline using the `
 from airia import AiriaClient
 
 client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 # Get pipeline configuration
 config = client.get_pipeline_config(pipeline_id="your_pipeline_id")
@@ -321,10 +384,117 @@ config = client.get_pipeline_config(pipeline_id="your_pipeline_id")
 print(f"Pipeline Name: {config.agent.name}")
 ```
 
+## Conversation Management
+
+You can create and manage conversations using the `create_conversation` method. Conversations allow you to organize and persist interactions within the Airia platform.
+
+### Creating Conversations
+
+#### Synchronous Usage
+
+```python
+from airia import AiriaClient
+
+client = AiriaClient(api_key="your_api_key")
+# Or with bearer token: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
+
+# Create a basic conversation
+conversation = client.create_conversation(
+    user_id="user_123"
+)
+print(f"Created conversation: {conversation.conversation_id}")
+print(f"WebSocket URL: {conversation.websocket_url}")
+
+# Create a conversation with all options
+conversation = client.create_conversation(
+    user_id="user_123",
+    title="My Research Session",
+    deployment_id="deployment_456", 
+    data_source_files={"documents": ["doc1.pdf", "doc2.txt"]},
+    is_bookmarked=True
+)
+print(f"Created bookmarked conversation: {conversation.conversation_id}")
+```
+
+#### Asynchronous Usage
+
+```python
+import asyncio
+from airia import AiriaAsyncClient
+
+async def main():
+    client = AiriaAsyncClient(api_key="your_api_key")
+    # Or with bearer token: client = AiriaAsyncClient.with_bearer_token(bearer_token="your_bearer_token")
+    
+    # Create a basic conversation
+    conversation = await client.create_conversation(
+        user_id="user_123"
+    )
+    print(f"Created conversation: {conversation.conversation_id}")
+    
+    # Create a conversation with all options
+    conversation = await client.create_conversation(
+        user_id="user_123",
+        title="My Research Session",
+        deployment_id="deployment_456",
+        data_source_files={"documents": ["doc1.pdf", "doc2.txt"]},
+        is_bookmarked=True
+    )
+    print(f"Created bookmarked conversation: {conversation.conversation_id}")
+
+asyncio.run(main())
+```
+
+### Conversation Parameters
+
+- **user_id** (required): The unique identifier of the user creating the conversation
+- **title** (optional): A descriptive title for the conversation
+- **deployment_id** (optional): The unique identifier of the deployment to associate with the conversation
+- **data_source_files** (optional): Configuration for data source files to be associated with the conversation
+- **is_bookmarked** (optional): Whether the conversation should be bookmarked (defaults to False)
+- **correlation_id** (optional): A unique identifier for request tracing and logging
+
+### Response Fields
+
+The `create_conversation` method returns a `CreateConversationResponse` object containing:
+
+- **conversation_id**: The unique identifier of the created conversation
+- **user_id**: The user ID associated with the conversation
+- **websocket_url**: The WebSocket URL for real-time communication
+- **deployment_id**: The deployment ID associated with the conversation
+- **icon_id** and **icon_url**: Optional conversation icon information
+- **description**: Optional conversation description
+- **space_name**: Optional workspace or space name
+
+## Authentication Methods
+
+Airia supports two authentication methods:
+
+### API Keys
+- Can be passed as a parameter or via `AIRIA_API_KEY` environment variable
+- Support gateway functionality (OpenAI and Anthropic gateways)
+- Suitable for long-term, persistent authentication
+
+### Bearer Tokens
+- Must be provided explicitly (no environment variable fallback)
+- **Important**: Bearer tokens cannot be used with gateway functionality
+- Suitable for ephemeral, short-lived authentication scenarios
+- Ideal for temporary access or programmatic token generation
+
+```python
+# ✅ API key with gateway support
+client = AiriaClient.with_openai_gateway(api_key="your_api_key")
+
+# ❌ Bearer token with gateway - NOT SUPPORTED
+# client = AiriaClient.with_openai_gateway(bearer_token="token")  # This won't work
+```
+
 ## Gateway Usage
 
 Airia provides gateway capabilities for popular AI services like OpenAI and Anthropic, allowing you to use your Airia API key with these services.
 
+> **Note**: Gateway functionality requires API key authentication. Bearer tokens are not supported for gateway usage.
+
 ### OpenAI Gateway
 
 ```python
@@ -452,7 +622,11 @@ console_logger = configure_logging(
 The SDK uses custom exceptions to provide clear error messages:
 
 ```python
-from airia import AiriaAPIError
+from airia import AiriaAPIError, AiriaClient
+
+# Works with both API keys and bearer tokens
+client = AiriaClient(api_key="your_api_key")
+# Or: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")
 
 try:
     response = client.execute_pipeline(