# 🐍 Mia21 Python SDK
Official Python client library for the Mia21 Chat API.
[](https://badge.fury.io/py/mia21)
[](https://pypi.org/project/mia21/)
[](LICENSE)
---
## 🚀 Quick Start
### Installation
```bash
pip install mia21
```
### Basic Usage
```python
from mia21 import Mia21Client
# Initialize client
client = Mia21Client(api_key="your-api-key-here")
# Start chat session
client.initialize(space_id="customer_support")
# Send a message
response = client.chat("How do I reset my password?")
print(response.message)
# Close session
client.close()
```
### Streaming Chat
```python
from mia21 import Mia21Client
client = Mia21Client(api_key="your-api-key-here")
client.initialize()
# Stream response in real-time
print("AI: ", end='', flush=True)
for chunk in client.stream_chat("Tell me a story"):
print(chunk, end='', flush=True)
print() # New line
client.close()
```
### Context Manager (Auto-Close)
```python
from mia21 import Mia21Client
with Mia21Client(api_key="your-api-key") as client:
client.initialize(space_id="sales_assistant")
response = client.chat("What are your pricing plans?")
print(response.message)
# Chat automatically closed
```
---
## 📚 API Reference
### `Mia21Client`
#### Constructor
```python
client = Mia21Client(
api_key: str, # Required: Your Mia21 API key
base_url: str = "...", # Optional: API base URL
user_id: str = None, # Optional: User ID (auto-generated if not provided)
timeout: int = 90 # Optional: Request timeout in seconds
)
```
#### Methods
**`list_spaces()`**
```python
spaces = client.list_spaces()
# Returns: List[Space]
for space in spaces:
print(f"{space.id}: {space.name} - {space.description}")
```
**`initialize()`**
```python
response = client.initialize(
space_id="customer_support", # Optional: Space to use
llm_type="openai", # Optional: "openai" or "gemini"
user_name="John", # Optional: User's name
language="en", # Optional: Force language
generate_first_message=True, # Optional: Generate greeting
incognito_mode=False # Optional: Privacy mode
)
# Returns: InitializeResponse
print(response.message) # AI's first message
```
**`chat()`**
```python
response = client.chat(
message="Hello!", # Required: User message
space_id="customer_support", # Optional: Which space
temperature=0.7, # Optional: 0.0-2.0
max_tokens=1024 # Optional: Max response length
)
# Returns: ChatResponse
print(response.message) # AI's response
print(response.tool_calls) # Tools executed (if any)
```
**`stream_chat()`**
```python
for chunk in client.stream_chat(
message="Tell me a story",
space_id="storyteller",
temperature=0.9
):
print(chunk, end='', flush=True)
# Yields: str (text chunks)
```
**`close()`**
```python
client.close(
space_id="customer_support" # Optional: Which space to close
)
# Saves conversation to database
```
---
## 🎯 Advanced Examples
### Multi-Space Conversation
```python
from mia21 import Mia21Client
client = Mia21Client(api_key="your-api-key")
# Initialize multiple spaces
client.initialize(space_id="support")
client.initialize(space_id="sales")
client.initialize(space_id="technical")
# Chat with different spaces independently
support_response = client.chat("I have a bug", space_id="support")
sales_response = client.chat("Pricing info?", space_id="sales")
tech_response = client.chat("API docs?", space_id="technical")
# Each space maintains separate conversation history
```
### Error Handling
```python
from mia21 import Mia21Client, ChatNotInitializedError, APIError
client = Mia21Client(api_key="your-api-key")
try:
# This will raise ChatNotInitializedError
client.chat("Hello") # Forgot to initialize!
except ChatNotInitializedError as e:
print(f"Error: {e}")
client.initialize() # Fix it
client.chat("Hello") # Now works
try:
response = client.chat("What's the weather?")
except APIError as e:
print(f"API Error: {e}")
```
### Async Integration (with asyncio)
```python
import asyncio
from mia21 import Mia21Client
async def chat_async():
client = Mia21Client(api_key="your-api-key")
client.initialize()
# Run in executor to avoid blocking
loop = asyncio.get_event_loop()
response = await loop.run_in_executor(
None,
client.chat,
"Hello from async!"
)
print(response.message)
client.close()
asyncio.run(chat_async())
```
---
## 🛠️ Configuration
### Environment Variables
```bash
# Set API key via environment
export MIA21_API_KEY="your-api-key-here"
export MIA21_BASE_URL="https://mia-api-staging-795279012747.us-central1.run.app"
```
```python
import os
from mia21 import Mia21Client
# Reads from environment variables
client = Mia21Client(
api_key=os.getenv("MIA21_API_KEY"),
base_url=os.getenv("MIA21_BASE_URL")
)
```
---
## 🧪 Testing
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/
# Run with coverage
pytest --cov=mia21 tests/
```
---
## 📄 License
MIT License - see LICENSE file for details.
---
## 🆘 Support
- **Documentation**: https://docs.mia21.com
- **API Reference**: https://docs.mia21.com/api
- **GitHub Issues**: https://github.com/mia21/python-sdk/issues
- **Email**: hello@earkick.com
---
## 🎉 Examples
See the `examples/` directory for complete working examples:
- `basic_chat.py` - Simple chat example
- `streaming_chat.py` - Streaming response example
- `multi_space.py` - Multiple spaces conversation
- `async_chat.py` - Asyncio integration
---
**Made with ❤️ by Mia21**
Raw data
{
"_id": null,
"home_page": "https://github.com/mia21/python-sdk",
"name": "mia21",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mia21 chat ai chatbot sdk api",
"author": "Mia21",
"author_email": "hello@earkick.com",
"download_url": "https://files.pythonhosted.org/packages/67/f4/a7f6269e24310fbcd6647cc9e00a9d9cdbbf95619bf84e2449018aa1857e/mia21-1.0.3.tar.gz",
"platform": null,
"description": "# \ud83d\udc0d Mia21 Python SDK\n\nOfficial Python client library for the Mia21 Chat API.\n\n[](https://badge.fury.io/py/mia21)\n[](https://pypi.org/project/mia21/)\n[](LICENSE)\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install mia21\n```\n\n### Basic Usage\n\n```python\nfrom mia21 import Mia21Client\n\n# Initialize client\nclient = Mia21Client(api_key=\"your-api-key-here\")\n\n# Start chat session\nclient.initialize(space_id=\"customer_support\")\n\n# Send a message\nresponse = client.chat(\"How do I reset my password?\")\nprint(response.message)\n\n# Close session\nclient.close()\n```\n\n### Streaming Chat\n\n```python\nfrom mia21 import Mia21Client\n\nclient = Mia21Client(api_key=\"your-api-key-here\")\nclient.initialize()\n\n# Stream response in real-time\nprint(\"AI: \", end='', flush=True)\nfor chunk in client.stream_chat(\"Tell me a story\"):\n print(chunk, end='', flush=True)\nprint() # New line\n\nclient.close()\n```\n\n### Context Manager (Auto-Close)\n\n```python\nfrom mia21 import Mia21Client\n\nwith Mia21Client(api_key=\"your-api-key\") as client:\n client.initialize(space_id=\"sales_assistant\")\n response = client.chat(\"What are your pricing plans?\")\n print(response.message)\n# Chat automatically closed\n```\n\n---\n\n## \ud83d\udcda API Reference\n\n### `Mia21Client`\n\n#### Constructor\n\n```python\nclient = Mia21Client(\n api_key: str, # Required: Your Mia21 API key\n base_url: str = \"...\", # Optional: API base URL\n user_id: str = None, # Optional: User ID (auto-generated if not provided)\n timeout: int = 90 # Optional: Request timeout in seconds\n)\n```\n\n#### Methods\n\n**`list_spaces()`**\n```python\nspaces = client.list_spaces()\n# Returns: List[Space]\n\nfor space in spaces:\n print(f\"{space.id}: {space.name} - {space.description}\")\n```\n\n**`initialize()`**\n```python\nresponse = client.initialize(\n space_id=\"customer_support\", # Optional: Space to use\n llm_type=\"openai\", # Optional: \"openai\" or \"gemini\"\n user_name=\"John\", # Optional: User's name\n language=\"en\", # Optional: Force language\n generate_first_message=True, # Optional: Generate greeting\n incognito_mode=False # Optional: Privacy mode\n)\n# Returns: InitializeResponse\n\nprint(response.message) # AI's first message\n```\n\n**`chat()`**\n```python\nresponse = client.chat(\n message=\"Hello!\", # Required: User message\n space_id=\"customer_support\", # Optional: Which space\n temperature=0.7, # Optional: 0.0-2.0\n max_tokens=1024 # Optional: Max response length\n)\n# Returns: ChatResponse\n\nprint(response.message) # AI's response\nprint(response.tool_calls) # Tools executed (if any)\n```\n\n**`stream_chat()`**\n```python\nfor chunk in client.stream_chat(\n message=\"Tell me a story\",\n space_id=\"storyteller\",\n temperature=0.9\n):\n print(chunk, end='', flush=True)\n# Yields: str (text chunks)\n```\n\n**`close()`**\n```python\nclient.close(\n space_id=\"customer_support\" # Optional: Which space to close\n)\n# Saves conversation to database\n```\n\n---\n\n## \ud83c\udfaf Advanced Examples\n\n### Multi-Space Conversation\n\n```python\nfrom mia21 import Mia21Client\n\nclient = Mia21Client(api_key=\"your-api-key\")\n\n# Initialize multiple spaces\nclient.initialize(space_id=\"support\")\nclient.initialize(space_id=\"sales\")\nclient.initialize(space_id=\"technical\")\n\n# Chat with different spaces independently\nsupport_response = client.chat(\"I have a bug\", space_id=\"support\")\nsales_response = client.chat(\"Pricing info?\", space_id=\"sales\")\ntech_response = client.chat(\"API docs?\", space_id=\"technical\")\n\n# Each space maintains separate conversation history\n```\n\n### Error Handling\n\n```python\nfrom mia21 import Mia21Client, ChatNotInitializedError, APIError\n\nclient = Mia21Client(api_key=\"your-api-key\")\n\ntry:\n # This will raise ChatNotInitializedError\n client.chat(\"Hello\") # Forgot to initialize!\nexcept ChatNotInitializedError as e:\n print(f\"Error: {e}\")\n client.initialize() # Fix it\n client.chat(\"Hello\") # Now works\n\ntry:\n response = client.chat(\"What's the weather?\")\nexcept APIError as e:\n print(f\"API Error: {e}\")\n```\n\n### Async Integration (with asyncio)\n\n```python\nimport asyncio\nfrom mia21 import Mia21Client\n\nasync def chat_async():\n client = Mia21Client(api_key=\"your-api-key\")\n client.initialize()\n \n # Run in executor to avoid blocking\n loop = asyncio.get_event_loop()\n response = await loop.run_in_executor(\n None, \n client.chat, \n \"Hello from async!\"\n )\n \n print(response.message)\n client.close()\n\nasyncio.run(chat_async())\n```\n\n---\n\n## \ud83d\udee0\ufe0f Configuration\n\n### Environment Variables\n\n```bash\n# Set API key via environment\nexport MIA21_API_KEY=\"your-api-key-here\"\nexport MIA21_BASE_URL=\"https://mia-api-staging-795279012747.us-central1.run.app\"\n```\n\n```python\nimport os\nfrom mia21 import Mia21Client\n\n# Reads from environment variables\nclient = Mia21Client(\n api_key=os.getenv(\"MIA21_API_KEY\"),\n base_url=os.getenv(\"MIA21_BASE_URL\")\n)\n```\n\n---\n\n## \ud83e\uddea Testing\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest tests/\n\n# Run with coverage\npytest --cov=mia21 tests/\n```\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details.\n\n---\n\n## \ud83c\udd98 Support\n\n- **Documentation**: https://docs.mia21.com\n- **API Reference**: https://docs.mia21.com/api\n- **GitHub Issues**: https://github.com/mia21/python-sdk/issues\n- **Email**: hello@earkick.com\n\n---\n\n## \ud83c\udf89 Examples\n\nSee the `examples/` directory for complete working examples:\n- `basic_chat.py` - Simple chat example\n- `streaming_chat.py` - Streaming response example\n- `multi_space.py` - Multiple spaces conversation\n- `async_chat.py` - Asyncio integration\n\n---\n\n**Made with \u2764\ufe0f by Mia21**\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Official Python SDK for Mia21 Chat API - Build AI chatbots in minutes",
"version": "1.0.3",
"project_urls": {
"Bug Reports": "https://github.com/mia21/python-sdk/issues",
"Documentation": "https://docs.mia21.com",
"Homepage": "https://github.com/mia21/python-sdk",
"Source": "https://github.com/mia21/python-sdk"
},
"split_keywords": [
"mia21",
"chat",
"ai",
"chatbot",
"sdk",
"api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "85e9317444141c3d3927930f1bd6acedfa19a1dbdd6dd9b87cc55b15ef1cd0fe",
"md5": "b8c97981c857236958e9d40055780997",
"sha256": "324a67e266311a851576126cd3eba71f8a58205e4f3ba0e3ec0c8bd92ebe0e0c"
},
"downloads": -1,
"filename": "mia21-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8c97981c857236958e9d40055780997",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10454,
"upload_time": "2025-10-28T14:43:05",
"upload_time_iso_8601": "2025-10-28T14:43:05.778012Z",
"url": "https://files.pythonhosted.org/packages/85/e9/317444141c3d3927930f1bd6acedfa19a1dbdd6dd9b87cc55b15ef1cd0fe/mia21-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "67f4a7f6269e24310fbcd6647cc9e00a9d9cdbbf95619bf84e2449018aa1857e",
"md5": "8c6928b3e0bb9a1a8551e9c30c16c885",
"sha256": "bc79857291ae1d14a914d7341c97b6b0a696a15fc49240d3a240af5c689f5603"
},
"downloads": -1,
"filename": "mia21-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "8c6928b3e0bb9a1a8551e9c30c16c885",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10576,
"upload_time": "2025-10-28T14:43:07",
"upload_time_iso_8601": "2025-10-28T14:43:07.457640Z",
"url": "https://files.pythonhosted.org/packages/67/f4/a7f6269e24310fbcd6647cc9e00a9d9cdbbf95619bf84e2449018aa1857e/mia21-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 14:43:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mia21",
"github_project": "python-sdk",
"github_not_found": true,
"lcname": "mia21"
}
JSON
