# puter-python-sdk
  
## 🚀 A Powerful Python SDK for Puter.js AI
Seamlessly integrate Puter.js AI models into your Python applications. The `puter-python-sdk` provides a robust and easy-to-use interface to access a wide range of large language models offered by Puter.js, enabling you to build intelligent applications with minimal effort.
Whether you're developing chatbots, content generators, or complex AI-driven workflows, this SDK simplifies the interaction with Puter.js's powerful AI capabilities.
## ✨ Features
- **Easy Authentication**: Securely log in using your Puter.js username and password.
- **Flexible Chat Interface**: Engage in dynamic conversations with various AI models.
- **Comprehensive Model Management**: Effortlessly switch between available AI models to suit your needs.
- **Automatic Chat History**: Conversation context is automatically maintained for coherent interactions.
- **Robust Error Handling**: Custom exceptions provide clear and concise error feedback for authentication and API issues.
- **Developer-Friendly**: Designed with simplicity and developer experience in mind, following Python best practices.
## 📦 Installation
Get started with `puter-python-sdk` in just one command!
### Quick Install (Recommended)
```bash
pip install puter-python-sdk
```
### Development Installation
If you want to contribute or modify the code:
1. **Clone the Repository**:
```bash
git clone https://github.com/CuzImSlymi/puter-python-sdk.git
cd puter-python-sdk
```
2. **Install Dependencies**:
It's highly recommended to use a virtual environment to manage your project dependencies.
```bash
# Create a virtual environment
python -m venv venv
# Activate the virtual environment
# On Windows:
# .\venv\Scripts\activate
# On macOS/Linux:
# source venv/bin/activate
# Install required packages
pip install -r requirements.txt
```
3. **Install the Library**:
Install the `puter-python-sdk` locally in editable mode (for development) or as a standard package.
```bash
# For development (editable mode)
pip install -e .
# Or as a standard package
pip install .
```
## ⚡ Quick Start
Run the `test_puter.py` script to quickly verify your setup and interact with the AI. This script will prompt you for your Puter.js credentials and allow you to chat directly.
```bash
python test_puter.py
```
## 📖 Usage Examples
### Basic Chat Interaction
After installing the library, you can import `PuterAI` and its exceptions into your Python scripts.
```python
from puter import PuterAI, PuterAuthError, PuterAPIError
# Replace with your actual Puter.js credentials
USERNAME = "your_puterjs_username"
PASSWORD = "your_puterjs_password"
try:
# Initialize the AI client
puter_ai = PuterAI(username=USERNAME, password=PASSWORD)
# Log in to Puter.js
if puter_ai.login():
print("Login successful!")
# Start a conversation
response = puter_ai.chat("Hello, how are you today?")
print(f"AI: {response}")
response = puter_ai.chat("What is the capital of France?")
print(f"AI: {response}")
# Clear chat history for a fresh start
puter_ai.clear_chat_history()
print("Chat history cleared.")
response = puter_ai.chat("Tell me a short, funny joke.")
print(f"AI: {response}")
else:
print("Login failed. Please check your credentials.")
except PuterAuthError as e:
print(f"Authentication Error: {e}")
except PuterAPIError as e:
print(f"API Error: {e}")
except Exception as e:
print(f"An Unexpected Error Occurred: {e}")
```
### Managing AI Models
Explore and switch between different AI models offered by Puter.js.
```python
from puter import PuterAI
# Assuming puter_ai client is already logged in as shown above
# puter_ai = PuterAI(username=USERNAME, password=PASSWORD)
# puter_ai.login()
# Get a list of all available models
models = puter_ai.get_available_models()
print("Available models:", models)
# Switch to a different model, e.g., gpt-5-nano
if puter_ai.set_model("gpt-5-nano"):
print(f"Model switched to: {puter_ai.current_model}")
response = puter_ai.chat("What is the meaning of life, according to GPT-5-nano?")
print(f"AI: {response}")
else:
print(f"Failed to switch model.")
# Switch back to claude-opus-4
if puter_ai.set_model("claude-opus-4"):
print(f"Model switched to: {puter_ai.current_model}")
response = puter_ai.chat("Tell me a short story about a space-faring cat.")
print(f"AI: {response}")
```
## 🌐 Available Models
Puter.js supports a variety of AI models. You can find the most up-to-date list and details on the official Puter.js models page [here](https://puter.com/puterai/chat/models).
This SDK now supports a wide range of models by dynamically determining the correct driver based on the model name. You can get a full list of available models by calling the `get_available_models()` method on an authenticated `PuterAI` instance.
## 🚨 Error Handling
The `puter-python-sdk` provides custom exceptions for more granular error management:
- `puter.PuterError`: The base exception for all library-specific errors.
- `puter.PuterAuthError`: Raised when authentication with Puter.js fails (e.g., incorrect credentials, network issues during login).
- `puter.PuterAPIError`: Raised when an API call to Puter.js fails after successful authentication (e.g., invalid model, rate limits, server errors).
## 🤝 Contributing
We welcome contributions! If you have suggestions, bug reports, or want to contribute code, please feel free to open an issue or submit a pull request on the [GitHub repository](https://github.com/CuzImSlymi/puter-python-sdk).
## 📄 License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/CuzImSlymi/puter-python-sdk",
"name": "puter-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ai, puter, sdk, chatbot, api",
"author": "Slymi",
"author_email": "Slymi <justin@slymi.org>",
"download_url": "https://files.pythonhosted.org/packages/5f/b2/185430351356bd1acb73571f05984533d3be6dede758c3cfc2c40e0e6617/puter_python_sdk-0.5.0.tar.gz",
"platform": null,
"description": "# puter-python-sdk\r\n\r\n  \r\n\r\n## \ud83d\ude80 A Powerful Python SDK for Puter.js AI\r\n\r\nSeamlessly integrate Puter.js AI models into your Python applications. The `puter-python-sdk` provides a robust and easy-to-use interface to access a wide range of large language models offered by Puter.js, enabling you to build intelligent applications with minimal effort.\r\n\r\nWhether you're developing chatbots, content generators, or complex AI-driven workflows, this SDK simplifies the interaction with Puter.js's powerful AI capabilities.\r\n\r\n## \u2728 Features\r\n\r\n- **Easy Authentication**: Securely log in using your Puter.js username and password.\r\n- **Flexible Chat Interface**: Engage in dynamic conversations with various AI models.\r\n- **Comprehensive Model Management**: Effortlessly switch between available AI models to suit your needs.\r\n- **Automatic Chat History**: Conversation context is automatically maintained for coherent interactions.\r\n- **Robust Error Handling**: Custom exceptions provide clear and concise error feedback for authentication and API issues.\r\n- **Developer-Friendly**: Designed with simplicity and developer experience in mind, following Python best practices.\r\n\r\n## \ud83d\udce6 Installation\r\n\r\nGet started with `puter-python-sdk` in just one command!\r\n\r\n### Quick Install (Recommended)\r\n\r\n```bash\r\npip install puter-python-sdk\r\n```\r\n\r\n### Development Installation\r\n\r\nIf you want to contribute or modify the code:\r\n\r\n1. **Clone the Repository**:\r\n\r\n ```bash\r\n git clone https://github.com/CuzImSlymi/puter-python-sdk.git\r\n cd puter-python-sdk\r\n ```\r\n\r\n2. **Install Dependencies**:\r\n\r\n It's highly recommended to use a virtual environment to manage your project dependencies.\r\n\r\n ```bash\r\n # Create a virtual environment\r\n python -m venv venv\r\n\r\n # Activate the virtual environment\r\n # On Windows:\r\n # .\\venv\\Scripts\\activate\r\n # On macOS/Linux:\r\n # source venv/bin/activate\r\n\r\n # Install required packages\r\n pip install -r requirements.txt\r\n ```\r\n\r\n3. **Install the Library**:\r\n\r\n Install the `puter-python-sdk` locally in editable mode (for development) or as a standard package.\r\n\r\n ```bash\r\n # For development (editable mode)\r\n pip install -e .\r\n\r\n # Or as a standard package\r\n pip install .\r\n ```\r\n\r\n## \u26a1 Quick Start\r\n\r\nRun the `test_puter.py` script to quickly verify your setup and interact with the AI. This script will prompt you for your Puter.js credentials and allow you to chat directly.\r\n\r\n```bash\r\npython test_puter.py\r\n```\r\n\r\n## \ud83d\udcd6 Usage Examples\r\n\r\n### Basic Chat Interaction\r\n\r\nAfter installing the library, you can import `PuterAI` and its exceptions into your Python scripts.\r\n\r\n```python\r\nfrom puter import PuterAI, PuterAuthError, PuterAPIError\r\n\r\n# Replace with your actual Puter.js credentials\r\nUSERNAME = \"your_puterjs_username\"\r\nPASSWORD = \"your_puterjs_password\"\r\n\r\ntry:\r\n # Initialize the AI client\r\n puter_ai = PuterAI(username=USERNAME, password=PASSWORD)\r\n\r\n # Log in to Puter.js\r\n if puter_ai.login():\r\n print(\"Login successful!\")\r\n\r\n # Start a conversation\r\n response = puter_ai.chat(\"Hello, how are you today?\")\r\n print(f\"AI: {response}\")\r\n\r\n response = puter_ai.chat(\"What is the capital of France?\")\r\n print(f\"AI: {response}\")\r\n\r\n # Clear chat history for a fresh start\r\n puter_ai.clear_chat_history()\r\n print(\"Chat history cleared.\")\r\n\r\n response = puter_ai.chat(\"Tell me a short, funny joke.\")\r\n print(f\"AI: {response}\")\r\n\r\n else:\r\n print(\"Login failed. Please check your credentials.\")\r\n\r\nexcept PuterAuthError as e:\r\n print(f\"Authentication Error: {e}\")\r\nexcept PuterAPIError as e:\r\n print(f\"API Error: {e}\")\r\nexcept Exception as e:\r\n print(f\"An Unexpected Error Occurred: {e}\")\r\n```\r\n\r\n### Managing AI Models\r\n\r\nExplore and switch between different AI models offered by Puter.js.\r\n\r\n```python\r\nfrom puter import PuterAI\r\n\r\n# Assuming puter_ai client is already logged in as shown above\r\n# puter_ai = PuterAI(username=USERNAME, password=PASSWORD)\r\n# puter_ai.login()\r\n\r\n# Get a list of all available models\r\nmodels = puter_ai.get_available_models()\r\nprint(\"Available models:\", models)\r\n\r\n# Switch to a different model, e.g., gpt-5-nano\r\nif puter_ai.set_model(\"gpt-5-nano\"):\r\n print(f\"Model switched to: {puter_ai.current_model}\")\r\n response = puter_ai.chat(\"What is the meaning of life, according to GPT-5-nano?\")\r\n print(f\"AI: {response}\")\r\nelse:\r\n print(f\"Failed to switch model.\")\r\n\r\n# Switch back to claude-opus-4\r\nif puter_ai.set_model(\"claude-opus-4\"):\r\n print(f\"Model switched to: {puter_ai.current_model}\")\r\n response = puter_ai.chat(\"Tell me a short story about a space-faring cat.\")\r\n print(f\"AI: {response}\")\r\n```\r\n\r\n## \ud83c\udf10 Available Models\r\n\r\nPuter.js supports a variety of AI models. You can find the most up-to-date list and details on the official Puter.js models page [here](https://puter.com/puterai/chat/models).\r\n\r\nThis SDK now supports a wide range of models by dynamically determining the correct driver based on the model name. You can get a full list of available models by calling the `get_available_models()` method on an authenticated `PuterAI` instance.\r\n\r\n## \ud83d\udea8 Error Handling\r\n\r\nThe `puter-python-sdk` provides custom exceptions for more granular error management:\r\n\r\n- `puter.PuterError`: The base exception for all library-specific errors.\r\n- `puter.PuterAuthError`: Raised when authentication with Puter.js fails (e.g., incorrect credentials, network issues during login).\r\n- `puter.PuterAPIError`: Raised when an API call to Puter.js fails after successful authentication (e.g., invalid model, rate limits, server errors).\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! If you have suggestions, bug reports, or want to contribute code, please feel free to open an issue or submit a pull request on the [GitHub repository](https://github.com/CuzImSlymi/puter-python-sdk).\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for accessing free AI models through Puter.js",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/CuzImSlymi/puter-python-sdk",
"Issues": "https://github.com/CuzImSlymi/puter-python-sdk/issues",
"Repository": "https://github.com/CuzImSlymi/puter-python-sdk"
},
"split_keywords": [
"ai",
" puter",
" sdk",
" chatbot",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "49b43cae9310924abc177ab708ff2da914e4ab0598bec5d649f8eb159fb5b351",
"md5": "c3c7b074d3f6738a89df49c855be97f0",
"sha256": "4d67dd44cdfb4c0e648fe1d3f52fa44455edd5da268ee6dffb659ae1b48b3cb0"
},
"downloads": -1,
"filename": "puter_python_sdk-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3c7b074d3f6738a89df49c855be97f0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14657,
"upload_time": "2025-10-19T15:16:34",
"upload_time_iso_8601": "2025-10-19T15:16:34.607631Z",
"url": "https://files.pythonhosted.org/packages/49/b4/3cae9310924abc177ab708ff2da914e4ab0598bec5d649f8eb159fb5b351/puter_python_sdk-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5fb2185430351356bd1acb73571f05984533d3be6dede758c3cfc2c40e0e6617",
"md5": "0484e84348d932c2c7ed7852979f8d30",
"sha256": "48071789b578c297f8a8b4b9a604b59229dc3a4ba408271e01a928e4d9cba3ac"
},
"downloads": -1,
"filename": "puter_python_sdk-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "0484e84348d932c2c7ed7852979f8d30",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 24301,
"upload_time": "2025-10-19T15:16:35",
"upload_time_iso_8601": "2025-10-19T15:16:35.505622Z",
"url": "https://files.pythonhosted.org/packages/5f/b2/185430351356bd1acb73571f05984533d3be6dede758c3cfc2c40e0e6617/puter_python_sdk-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 15:16:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CuzImSlymi",
"github_project": "puter-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "asyncio-throttle",
"specs": [
[
">=",
"1.0.2"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
}
],
"lcname": "puter-python-sdk"
}
JSON
