<p align="center">
<img src="https://auth.kosmoy.ai/assets/icons/studio_logo.svg" alt="Kosmoy Studio Logo">
</p>
# Kosmoy SDK
[](https://www.python.org/downloads/release/python-370/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/kosmoy-sdk/)
The **Kosmoy SDK** is a powerful Python library designed to seamlessly integrate your code with the **Kosmoy platform**. It empowers your applications to leverage **Kosmoy Gateways**, providing secure and governed access to AI models and routers configured within **Kosmoy Studio**.
This SDK is built with compatibility in mind, offering a similar interface to the standard OpenAI Python SDK and providing built-in integration with LangChain. This makes it easy to adopt the Kosmoy SDK, whether you are starting a new project or migrating an existing one.
## Key Features
* **Secure Access to Kosmoy Gateways:** Connect your Python applications to Kosmoy Gateways via a secure API key associated with a Kosmoy Studio Coded App.
* **Simplified Model Interaction:** Interact with AI models (LLMs) registered in Kosmoy Studio using a familiar interface.
* **Leverage Studio Configurations:** Benefit from the Routers and Guardrails configured within Kosmoy Studio, ensuring your application adheres to organizational policies.
* **OpenAI SDK Compatibility:** Offers a similar interface to the standard OpenAI client for easy migration and adoption.
* **LangChain Integration:** Provides seamless integration with LangChain for building sophisticated language model applications.
* **Comprehensive Error Handling:** Implements robust error handling inherited from both the OpenAI and LangChain APIs.
* **Observability and Monitoring:** Gain insights into your application's performance, usage, and costs through Kosmoy Studio's Insights.
* **Automatic Retries:** Built-in retry mechanism for handling transient network issues.
* **Type Hints:** Includes type hints for improved code readability and maintainability.
## Installation
### Standard Usage
```bash
pip install kosmoy-sdk
```
### LangChain Integration
```bash
pip install kosmoy-sdk[langchain]
```
## Requirements
* Python 3.7+
## Quick Start
### Standard Usage
```python
from kosmoy_sdk import GatewayClient
# Initialize the client
client = GatewayClient(
app_id="your_app_id",
api_key="your_api_key"
)
# Interact with a model (make sure the model is available in your Gateway)
response = client.client.chat.completions.create(
model="gpt-4", # Replace with your model name configured in Kosmoy Studio
messages=[{"role": "user", "content": "Hello!"}],
)
# Get Gateway Information
gateway_info = client.get_gateway()
```
### LangChain Integration
```python
from kosmoy_sdk.langchain import KosmoyGatewayLangchain
# Initialize the LangChain client
client = KosmoyGatewayLangchain(
app_id="your_app_id", # Replace with your Coded App ID
api_key="your_api_key", # Replace with your API key
model="gpt-4", # Replace with your model name configured in Kosmoy Studio,
)
# Create messages
messages = [
("system", "You are a helpful assistant."),
("human", "What is the capital of France?")
]
# Get a response
response = client.invoke(messages)
# Get Gateway information
gateway_info = client.get_gateway()
```
### Gateway information
```python
gateway_info = client.get_gateway()
```
<details><summary>JSON Sample</summary>
```json
{
"id": 1,
"name": "AI Text Generator",
"description": "A coded app that generates text using AI models.",
"gateway_id": 100,
"created_at": "2025-02-10T12:00:00Z",
"created_by_user": {
"id": 5,
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"role": "Admin"
},
"gateway": {
"id": 100,
"name": "gateway1",
"description": "Gateway handling AI text processing requests.",
"created_at": "2025-01-15T10:30:00Z",
"created_by_user": {
"id": 2,
"first_name": "Alice",
"last_name": "Smith",
"email": "alice.smith@example.com",
"role": "Root"
},
"models": [
{
"id": 201,
"service_config_id": 301,
"name": "gpt4o",
"model_name": "gpt-4o",
"description": "High-performance text generation model.",
"config_params": {
"temperature": 0.7,
"max_tokens": 500
}
}
],
"guardrails": [
{
"id": 10,
"name": "guardrail1",
"description": "Filters out inappropriate language."
}
],
"routers": [
{
"id": 50,
"name": "routers1",
"description": "Routes requests between different AI models.",
"error_message": "Fallback to secondary model.",
"primary_model_id": 201,
"secondary_model_id": 202,
"router_type": "FAILOVER",
"created_by_user": {
"id": 3,
"first_name": "Bob",
"last_name": "Johnson",
"email": "bob.johnson@example.com",
"role": "Admin"
}
}
]
}
}
```
</details>
## Configuration
The Kosmoy SDK requires the following parameters:
* **app_id:** Your Kosmoy Studio Coded App ID (required).
* **api_key:** Your Kosmoy Studio Coded App API key (required).
* **timeout:** Request timeout in seconds (optional, default: 30).
* **max_retries:** Maximum number of retry attempts (optional, default: 3).
## How to get you Kosmoy Studio Coded App ID and API Key
1. Log in to Kosmoy Studio: Access the Kosmoy Studio platform at [https://www.kosmoy.com](https://auth.kosmoy.ai/login)
2. Create a Coded App: Navigate to the "Coded Apps" section and create a new Coded App.
3. Assign a Gateway: Associate your Coded App with a configured Gateway.
4. Retrieve Credentials: The API key and App ID will be displayed in the Coded App details.
## Error Handling
The Kosmoy SDK inherits error handling from the OpenAI API (when used directly) and LangChain API (when using the LangChain integration). It also includes an automatic retry mechanism for failed requests.
## Security
* API credentials are transmitted securely via request headers.
* The base URL for API communication is pre-configured within the SDK.
* HTTPS is enforced for all API communications.
## Learn More
* Kosmoy Website: [https://www.kosmoy.com](https://www.kosmoy.com)
* Kosmoy Documentation: [https://docs.kosmoy.com](https://docs.kosmoy.com)
## License
This project is licensed under the MIT license.
## Support
For support, please contact support@kosmoy.com
Raw data
{
"_id": null,
"home_page": "https://github.com/KosmoyAI/kosmoy-sdk",
"name": "kosmoy-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Olsi Hoxha",
"author_email": "olsi.hoxha@kosmoy.com",
"download_url": "https://files.pythonhosted.org/packages/6c/54/0842ec1f3ee572d5d870c64a92b1aa99170df44007691c788e92ef49fa06/kosmoy_sdk-0.1.8.dev0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://auth.kosmoy.ai/assets/icons/studio_logo.svg\" alt=\"Kosmoy Studio Logo\">\n</p>\n\n# Kosmoy SDK\n\n[](https://www.python.org/downloads/release/python-370/)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/kosmoy-sdk/)\n\nThe **Kosmoy SDK** is a powerful Python library designed to seamlessly integrate your code with the **Kosmoy platform**. It empowers your applications to leverage **Kosmoy Gateways**, providing secure and governed access to AI models and routers configured within **Kosmoy Studio**.\n\nThis SDK is built with compatibility in mind, offering a similar interface to the standard OpenAI Python SDK and providing built-in integration with LangChain. This makes it easy to adopt the Kosmoy SDK, whether you are starting a new project or migrating an existing one.\n\n## Key Features\n\n* **Secure Access to Kosmoy Gateways:** Connect your Python applications to Kosmoy Gateways via a secure API key associated with a Kosmoy Studio Coded App.\n* **Simplified Model Interaction:** Interact with AI models (LLMs) registered in Kosmoy Studio using a familiar interface.\n* **Leverage Studio Configurations:** Benefit from the Routers and Guardrails configured within Kosmoy Studio, ensuring your application adheres to organizational policies.\n* **OpenAI SDK Compatibility:** Offers a similar interface to the standard OpenAI client for easy migration and adoption.\n* **LangChain Integration:** Provides seamless integration with LangChain for building sophisticated language model applications.\n* **Comprehensive Error Handling:** Implements robust error handling inherited from both the OpenAI and LangChain APIs.\n* **Observability and Monitoring:** Gain insights into your application's performance, usage, and costs through Kosmoy Studio's Insights.\n* **Automatic Retries:** Built-in retry mechanism for handling transient network issues.\n* **Type Hints:** Includes type hints for improved code readability and maintainability.\n\n## Installation\n\n### Standard Usage\n\n```bash\npip install kosmoy-sdk\n```\n\n### LangChain Integration\n\n```bash\npip install kosmoy-sdk[langchain]\n```\n\n## Requirements\n\n* Python 3.7+\n\n## Quick Start\n\n### Standard Usage\n\n```python\nfrom kosmoy_sdk import GatewayClient\n\n\n# Initialize the client\nclient = GatewayClient(\n app_id=\"your_app_id\", \n api_key=\"your_api_key\"\n)\n\n# Interact with a model (make sure the model is available in your Gateway)\n\nresponse = client.client.chat.completions.create(\n model=\"gpt-4\", # Replace with your model name configured in Kosmoy Studio\n messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n)\n\n# Get Gateway Information\ngateway_info = client.get_gateway()\n```\n\n### LangChain Integration\n\n```python\nfrom kosmoy_sdk.langchain import KosmoyGatewayLangchain\n\n# Initialize the LangChain client\nclient = KosmoyGatewayLangchain(\n app_id=\"your_app_id\", # Replace with your Coded App ID\n api_key=\"your_api_key\", # Replace with your API key\n model=\"gpt-4\", # Replace with your model name configured in Kosmoy Studio,\n)\n\n# Create messages\nmessages = [\n (\"system\", \"You are a helpful assistant.\"),\n (\"human\", \"What is the capital of France?\")\n]\n\n# Get a response\nresponse = client.invoke(messages)\n\n# Get Gateway information\ngateway_info = client.get_gateway()\n```\n\n### Gateway information\n\n```python\ngateway_info = client.get_gateway()\n```\n<details><summary>JSON Sample</summary>\n \n```json\n{\n \"id\": 1,\n \"name\": \"AI Text Generator\",\n \"description\": \"A coded app that generates text using AI models.\",\n \"gateway_id\": 100,\n \"created_at\": \"2025-02-10T12:00:00Z\",\n \"created_by_user\": {\n \"id\": 5,\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"role\": \"Admin\"\n },\n \"gateway\": {\n \"id\": 100,\n \"name\": \"gateway1\",\n \"description\": \"Gateway handling AI text processing requests.\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"created_by_user\": {\n \"id\": 2,\n \"first_name\": \"Alice\",\n \"last_name\": \"Smith\",\n \"email\": \"alice.smith@example.com\",\n \"role\": \"Root\"\n },\n \"models\": [\n {\n \"id\": 201,\n \"service_config_id\": 301,\n \"name\": \"gpt4o\",\n \"model_name\": \"gpt-4o\",\n \"description\": \"High-performance text generation model.\",\n \"config_params\": {\n \"temperature\": 0.7,\n \"max_tokens\": 500\n }\n }\n ],\n \"guardrails\": [\n {\n \"id\": 10,\n \"name\": \"guardrail1\",\n \"description\": \"Filters out inappropriate language.\"\n }\n ],\n \"routers\": [\n {\n \"id\": 50,\n \"name\": \"routers1\",\n \"description\": \"Routes requests between different AI models.\",\n \"error_message\": \"Fallback to secondary model.\",\n \"primary_model_id\": 201,\n \"secondary_model_id\": 202,\n \"router_type\": \"FAILOVER\",\n \"created_by_user\": {\n \"id\": 3,\n \"first_name\": \"Bob\",\n \"last_name\": \"Johnson\",\n \"email\": \"bob.johnson@example.com\",\n \"role\": \"Admin\"\n }\n }\n ]\n }\n}\n```\n\n</details>\n\n## Configuration \n\nThe Kosmoy SDK requires the following parameters:\n\n* **app_id:** Your Kosmoy Studio Coded App ID (required).\n* **api_key:** Your Kosmoy Studio Coded App API key (required).\n* **timeout:** Request timeout in seconds (optional, default: 30).\n* **max_retries:** Maximum number of retry attempts (optional, default: 3).\n\n## How to get you Kosmoy Studio Coded App ID and API Key\n\n1. Log in to Kosmoy Studio: Access the Kosmoy Studio platform at [https://www.kosmoy.com](https://auth.kosmoy.ai/login)\n2. Create a Coded App: Navigate to the \"Coded Apps\" section and create a new Coded App.\n3. Assign a Gateway: Associate your Coded App with a configured Gateway.\n4. Retrieve Credentials: The API key and App ID will be displayed in the Coded App details.\n\n## Error Handling\n\nThe Kosmoy SDK inherits error handling from the OpenAI API (when used directly) and LangChain API (when using the LangChain integration). It also includes an automatic retry mechanism for failed requests.\n\n## Security\n\n* API credentials are transmitted securely via request headers.\n* The base URL for API communication is pre-configured within the SDK.\n* HTTPS is enforced for all API communications.\n\n## Learn More\n\n* Kosmoy Website: [https://www.kosmoy.com](https://www.kosmoy.com)\n* Kosmoy Documentation: [https://docs.kosmoy.com](https://docs.kosmoy.com)\n\n## License\n\nThis project is licensed under the MIT license.\n\n## Support\n\nFor support, please contact support@kosmoy.com\n",
"bugtrack_url": null,
"license": null,
"summary": "A Gateway SDK for making API requests",
"version": "0.1.8.dev0",
"project_urls": {
"Homepage": "https://github.com/KosmoyAI/kosmoy-sdk"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de70892a12b90882ae03d4dbd0901038a46e93ff632c1c7e4b1e03252eb782fc",
"md5": "f0a8ed388cf879591512f2a94c5c5168",
"sha256": "596f8dda0da7df5e9c7a245d8951b08dbdf49bd1fdacd683318cc589827b9cf2"
},
"downloads": -1,
"filename": "kosmoy_sdk-0.1.8.dev0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0a8ed388cf879591512f2a94c5c5168",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9049,
"upload_time": "2025-07-21T08:31:14",
"upload_time_iso_8601": "2025-07-21T08:31:14.444879Z",
"url": "https://files.pythonhosted.org/packages/de/70/892a12b90882ae03d4dbd0901038a46e93ff632c1c7e4b1e03252eb782fc/kosmoy_sdk-0.1.8.dev0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6c540842ec1f3ee572d5d870c64a92b1aa99170df44007691c788e92ef49fa06",
"md5": "c6cebdc2314ba056346a2026cbe8ee5a",
"sha256": "80d3f0698585f42bd62630541d17e26404d399d5773735a6ae180dfaebe4338b"
},
"downloads": -1,
"filename": "kosmoy_sdk-0.1.8.dev0.tar.gz",
"has_sig": false,
"md5_digest": "c6cebdc2314ba056346a2026cbe8ee5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10081,
"upload_time": "2025-07-21T08:31:15",
"upload_time_iso_8601": "2025-07-21T08:31:15.612053Z",
"url": "https://files.pythonhosted.org/packages/6c/54/0842ec1f3ee572d5d870c64a92b1aa99170df44007691c788e92ef49fa06/kosmoy_sdk-0.1.8.dev0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 08:31:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KosmoyAI",
"github_project": "kosmoy-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"2.11.5"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.32.3"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.82.1"
]
]
},
{
"name": "h11",
"specs": [
[
">=",
"0.16.0"
]
]
}
],
"lcname": "kosmoy-sdk"
}
JSON
