# Sunholo Python Library
[](https://pypi.python.org/pypi/sunholo/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://pypi.python.org/pypi/sunholo/)
🚀 **AI DevOps framework for building GenAI applications on Google Cloud Platform**
Sunholo is a comprehensive Python framework that streamlines the development, deployment, and management of Generative AI applications (VACs - Virtual Agent Computers). It provides a configuration-driven approach with deep integration into Google Cloud services while supporting multiple AI providers.
## 🎯 What is Sunholo?
Sunholo helps you:
- 🤖 Build conversational AI agents with any LLM provider (Vertex AI, OpenAI, Anthropic, Ollama)
- ☁️ Deploy to Google Cloud Run with automatic scaling
- 🗄️ Use AlloyDB and Discovery Engine for vector storage and search
- 🔄 Handle streaming responses and async processing
- 📄 Process documents with chunking and embedding pipelines
- 🔧 Manage complex configurations with YAML files
- 🎨 Create APIs, web apps, and chat bots
## 🚀 Quick Start
### Prerequisites
Install [uv](https://docs.astral.sh/uv/) - a fast, modern Python package manager:
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Installation
```bash
# Install with CLI tools (recommended)
uv tool install --from "sunholo[cli]" sunholo
# Install with all features including GCP
uv tool install --from "sunholo[cli]" sunholo --with "sunholo[all]"
```
### Your First VAC
1. **Initialize a new project:**
```bash
sunholo init my-ai-agent
cd my-ai-agent
```
2. **Configure your AI agent:**
Edit `config/vac_config.yaml`:
```yaml
kind: vacConfig
apiVersion: v1
vac:
my-agent:
llm: vertex
model: gemini-1.5-pro
agent: simple
description: "My AI agent powered by Google Cloud"
```
3. **Chat with your agent locally:**
```bash
sunholo vac chat my-agent
```
4. **Run your agent as a local Flask app:**
```bash
sunholo deploy my-agent
```
## 📋 Features
### Core Capabilities
- **Multi-Model Support**: Integrate Vertex AI, OpenAI, Anthropic, Ollama in one app
- **Document Processing**: Chunk, embed, and index documents with Discovery Engine
- **Vector Databases**: Native support for AlloyDB, LanceDB, Supabase
- **Streaming**: Real-time response streaming for chat applications
- **Async Processing**: Pub/Sub integration for background tasks
- **Authentication**: Built-in Google Cloud IAM and custom auth
### Google Cloud Integration
- **Vertex AI**: Access Gemini, PaLM, and custom models
- **AlloyDB**: PostgreSQL-compatible vector database
- **Discovery Engine**: Enterprise search and RAG
- **Cloud Run**: Serverless deployment
- **Cloud Storage**: Document and file management
- **Pub/Sub**: Asynchronous message processing
- **Cloud Logging**: Centralized logging
### Framework Support
- **Web Frameworks**: Flask and FastAPI templates
- **AI Frameworks**: LangChain and LlamaIndex integration
- **MCP Integration**: Model Context Protocol server and client support
- **Observability**: Langfuse for tracing and monitoring
- **API Standards**: OpenAI-compatible endpoints
## 🛠 Installation Options
### Using uv
```bash
# Core CLI features
uv tool install --from "sunholo[cli]" sunholo
# With Google Cloud Platform integration
uv tool install --from "sunholo[cli]" sunholo --with "sunholo[gcp]"
# With specific LLM providers
uv tool install --from "sunholo[cli]" sunholo --with "sunholo[openai]"
uv tool install --from "sunholo[cli]" sunholo --with "sunholo[anthropic]"
# With database support
uv tool install --from "sunholo[cli]" sunholo --with "sunholo[database]"
# Everything
uv tool install --from "sunholo[cli]" sunholo --with "sunholo[all]"
```
### Managing Installations
```bash
# Upgrade
uv tool upgrade sunholo
# List installed
uv tool list
# Uninstall
uv tool uninstall sunholo
```
### Development Setup
```bash
# Clone repository
git clone https://github.com/sunholo-data/sunholo-py.git
cd sunholo-py
# Install in development mode
uv venv
uv pip install -e ".[all]"
# Run tests
pytest tests/
```
## ⚙️ Configuration
Sunholo uses YAML configuration files:
```yaml
# config/vac_config.yaml
kind: vacConfig
apiVersion: v1
gcp_config:
project_id: my-gcp-project
location: us-central1
vac:
my-agent:
llm: vertex
model: gemini-1.5-pro
agent: langchain
memory:
- alloydb:
project_id: my-gcp-project
region: us-central1
cluster: my-cluster
instance: my-instance
tools:
- search
- calculator
```
## 🔧 CLI Commands
```bash
# Project Management
sunholo init <project-name> # Create new project from template
sunholo list-configs # List all configurations
sunholo list-configs --validate # Validate configurations
# Development
sunholo vac chat <vac-name> # Chat with a VAC locally
sunholo vac list # List available VACs
sunholo vac get-url <vac-name> # Get Cloud Run URL for a VAC
sunholo proxy start <service> # Start local proxy to cloud service
sunholo proxy list # List running proxies
sunholo deploy <vac-name> # Run Flask app locally
# Document Processing
sunholo embed <vac-name> # Process and embed documents
sunholo merge-text <folder> <output> # Merge files for context
# Cloud Services
sunholo discovery-engine create <name> # Create Discovery Engine instance
sunholo vertex list-extensions # List Vertex AI extensions
sunholo swagger <vac-name> # Generate OpenAPI spec
# Integration Tools
sunholo excel-init # Initialize Excel plugin
sunholo llamaindex <query> # Query with LlamaIndex
sunholo mcp list-tools # List MCP tools
sunholo tts <text> # Text-to-speech synthesis
```
## 📝 Examples
### Chat with History Extraction
```python
from sunholo.utils import ConfigManager
from sunholo.components import pick_llm
from sunholo.agents import extract_chat_history
config = ConfigManager('my-agent')
llm = pick_llm(config=config)
# Extract chat history from messages
chat_history = [
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi there!"}
]
history_str = extract_chat_history(chat_history)
# Use in prompt
response = llm.invoke(f"Given this history:\n{history_str}\n\nUser: How are you?")
```
### Document Processing with Chunker
```python
from sunholo.chunker import direct_file_to_embed
from sunholo.utils import ConfigManager
config = ConfigManager('my-agent')
# Process a file directly
result = direct_file_to_embed(
"document.pdf",
embed_prefix="doc",
metadata={"source": "user_upload"},
vectorstore=config.vacConfig("vectorstore")
)
```
### Vertex AI with Memory Tools
```python
from sunholo.vertex import get_vertex_memories
from sunholo.utils import ConfigManager
config = ConfigManager('my-agent')
# Get Vertex AI memory configuration
memory_config = get_vertex_memories(config)
# Use with Vertex AI
if memory_config:
print(f"Memory tools configured: {memory_config}")
```
### Streaming Response with Flask
```python
from sunholo.agents import send_to_qa
from flask import Response, request
@app.route('/vac/streaming/<vac_name>', methods=['POST'])
def streaming_endpoint(vac_name):
question = request.json.get('user_input')
def generate():
# Stream responses from the QA system
response = send_to_qa(
question,
vac_name=vac_name,
stream=True
)
if hasattr(response, '__iter__'):
for chunk in response:
yield f"data: {chunk}\n\n"
else:
yield f"data: {response}\n\n"
return Response(generate(), content_type='text/event-stream')
```
### Discovery Engine Integration
```python
from sunholo.discovery_engine import DiscoveryEngineClient
# Initialize client
client = DiscoveryEngineClient(
project_id='my-project',
data_store_id='my-datastore'
)
# Search documents
results = client.search("What is Vertex AI?")
for result in results:
print(f"Content: {result.chunk.content}")
print(f"Score: {result.relevance_score}")
```
## 🧪 Testing
```bash
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_config.py
# Run with coverage
pytest --cov=src/sunholo tests/
# Run async tests
pytest tests/test_async_genai2.py
```
## 📚 Documentation
- 📖 **Full Documentation**: https://dev.sunholo.com/
- 🎓 **Tutorials**: https://dev.sunholo.com/docs/howto/
- 🤖 **VAC Examples**: https://github.com/sunholo-data/vacs-public
- 🎧 **Audio Overview**: [Listen to the NotebookLM podcast](https://drive.google.com/file/d/1GvwRmiYDjPjN2hXQ8plhnVDByu6TmgCQ/view?usp=drive_link)
## 🤝 Contributing
We welcome contributions! See our [Contributing Guidelines](CONTRIBUTING.md).
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📜 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE.txt) file for details.
```
Copyright [2024] [Holosun ApS]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
```
## 🙏 Support
- 📧 Email: multivac@sunholo.com
- 🐛 Issues: [GitHub Issues](https://github.com/sunholo-data/sunholo-py/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/sunholo-data/sunholo-py/discussions)
- 📖 Documentation: https://dev.sunholo.com/
Raw data
{
"_id": null,
"home_page": null,
"name": "sunholo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "llms, devops, google_cloud_platform",
"author": null,
"author_email": "Holosun ApS <multivac@sunholo.com>",
"download_url": "https://files.pythonhosted.org/packages/ca/bb/01ee0b6159d7583db350edf769a83cd6f4aafcb0bafd1d4786d7dfcb8c98/sunholo-0.144.12.tar.gz",
"platform": null,
"description": "# Sunholo Python Library\n\n[](https://pypi.python.org/pypi/sunholo/)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://pypi.python.org/pypi/sunholo/)\n\n\ud83d\ude80 **AI DevOps framework for building GenAI applications on Google Cloud Platform**\n\nSunholo is a comprehensive Python framework that streamlines the development, deployment, and management of Generative AI applications (VACs - Virtual Agent Computers). It provides a configuration-driven approach with deep integration into Google Cloud services while supporting multiple AI providers.\n\n## \ud83c\udfaf What is Sunholo?\n\nSunholo helps you:\n- \ud83e\udd16 Build conversational AI agents with any LLM provider (Vertex AI, OpenAI, Anthropic, Ollama)\n- \u2601\ufe0f Deploy to Google Cloud Run with automatic scaling\n- \ud83d\uddc4\ufe0f Use AlloyDB and Discovery Engine for vector storage and search\n- \ud83d\udd04 Handle streaming responses and async processing\n- \ud83d\udcc4 Process documents with chunking and embedding pipelines\n- \ud83d\udd27 Manage complex configurations with YAML files\n- \ud83c\udfa8 Create APIs, web apps, and chat bots\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\nInstall [uv](https://docs.astral.sh/uv/) - a fast, modern Python package manager:\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Windows\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n### Installation\n\n```bash\n# Install with CLI tools (recommended)\nuv tool install --from \"sunholo[cli]\" sunholo\n\n# Install with all features including GCP\nuv tool install --from \"sunholo[cli]\" sunholo --with \"sunholo[all]\"\n```\n\n### Your First VAC\n\n1. **Initialize a new project:**\n```bash\nsunholo init my-ai-agent\ncd my-ai-agent\n```\n\n2. **Configure your AI agent:**\nEdit `config/vac_config.yaml`:\n```yaml\nkind: vacConfig\napiVersion: v1\nvac:\n my-agent:\n llm: vertex\n model: gemini-1.5-pro\n agent: simple\n description: \"My AI agent powered by Google Cloud\"\n```\n\n3. **Chat with your agent locally:**\n```bash\nsunholo vac chat my-agent\n```\n\n4. **Run your agent as a local Flask app:**\n```bash\nsunholo deploy my-agent\n```\n\n## \ud83d\udccb Features\n\n### Core Capabilities\n\n- **Multi-Model Support**: Integrate Vertex AI, OpenAI, Anthropic, Ollama in one app\n- **Document Processing**: Chunk, embed, and index documents with Discovery Engine\n- **Vector Databases**: Native support for AlloyDB, LanceDB, Supabase\n- **Streaming**: Real-time response streaming for chat applications\n- **Async Processing**: Pub/Sub integration for background tasks\n- **Authentication**: Built-in Google Cloud IAM and custom auth\n\n### Google Cloud Integration\n\n- **Vertex AI**: Access Gemini, PaLM, and custom models\n- **AlloyDB**: PostgreSQL-compatible vector database\n- **Discovery Engine**: Enterprise search and RAG\n- **Cloud Run**: Serverless deployment\n- **Cloud Storage**: Document and file management\n- **Pub/Sub**: Asynchronous message processing\n- **Cloud Logging**: Centralized logging\n\n### Framework Support\n\n- **Web Frameworks**: Flask and FastAPI templates\n- **AI Frameworks**: LangChain and LlamaIndex integration\n- **MCP Integration**: Model Context Protocol server and client support\n- **Observability**: Langfuse for tracing and monitoring\n- **API Standards**: OpenAI-compatible endpoints\n\n## \ud83d\udee0 Installation Options\n\n### Using uv\n\n```bash\n# Core CLI features\nuv tool install --from \"sunholo[cli]\" sunholo\n\n# With Google Cloud Platform integration\nuv tool install --from \"sunholo[cli]\" sunholo --with \"sunholo[gcp]\"\n\n# With specific LLM providers\nuv tool install --from \"sunholo[cli]\" sunholo --with \"sunholo[openai]\"\nuv tool install --from \"sunholo[cli]\" sunholo --with \"sunholo[anthropic]\"\n\n# With database support\nuv tool install --from \"sunholo[cli]\" sunholo --with \"sunholo[database]\"\n\n# Everything\nuv tool install --from \"sunholo[cli]\" sunholo --with \"sunholo[all]\"\n```\n\n### Managing Installations\n\n```bash\n# Upgrade\nuv tool upgrade sunholo\n\n# List installed\nuv tool list\n\n# Uninstall\nuv tool uninstall sunholo\n```\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/sunholo-data/sunholo-py.git\ncd sunholo-py\n\n# Install in development mode\nuv venv\nuv pip install -e \".[all]\"\n\n# Run tests\npytest tests/\n```\n\n## \u2699\ufe0f Configuration\n\nSunholo uses YAML configuration files:\n\n```yaml\n# config/vac_config.yaml\nkind: vacConfig\napiVersion: v1\ngcp_config:\n project_id: my-gcp-project\n location: us-central1\nvac:\n my-agent:\n llm: vertex\n model: gemini-1.5-pro\n agent: langchain\n memory:\n - alloydb:\n project_id: my-gcp-project\n region: us-central1\n cluster: my-cluster\n instance: my-instance\n tools:\n - search\n - calculator\n```\n\n## \ud83d\udd27 CLI Commands\n\n```bash\n# Project Management\nsunholo init <project-name> # Create new project from template\nsunholo list-configs # List all configurations\nsunholo list-configs --validate # Validate configurations\n\n# Development\nsunholo vac chat <vac-name> # Chat with a VAC locally\nsunholo vac list # List available VACs \nsunholo vac get-url <vac-name> # Get Cloud Run URL for a VAC\nsunholo proxy start <service> # Start local proxy to cloud service\nsunholo proxy list # List running proxies\nsunholo deploy <vac-name> # Run Flask app locally\n\n# Document Processing\nsunholo embed <vac-name> # Process and embed documents\nsunholo merge-text <folder> <output> # Merge files for context\n\n# Cloud Services\nsunholo discovery-engine create <name> # Create Discovery Engine instance\nsunholo vertex list-extensions # List Vertex AI extensions\nsunholo swagger <vac-name> # Generate OpenAPI spec\n\n# Integration Tools\nsunholo excel-init # Initialize Excel plugin\nsunholo llamaindex <query> # Query with LlamaIndex\nsunholo mcp list-tools # List MCP tools\nsunholo tts <text> # Text-to-speech synthesis\n```\n\n## \ud83d\udcdd Examples\n\n### Chat with History Extraction\n\n```python\nfrom sunholo.utils import ConfigManager\nfrom sunholo.components import pick_llm\nfrom sunholo.agents import extract_chat_history\n\nconfig = ConfigManager('my-agent')\nllm = pick_llm(config=config)\n\n# Extract chat history from messages\nchat_history = [\n {\"role\": \"user\", \"content\": \"Hello\"},\n {\"role\": \"assistant\", \"content\": \"Hi there!\"}\n]\nhistory_str = extract_chat_history(chat_history)\n\n# Use in prompt\nresponse = llm.invoke(f\"Given this history:\\n{history_str}\\n\\nUser: How are you?\")\n```\n\n### Document Processing with Chunker\n\n```python\nfrom sunholo.chunker import direct_file_to_embed\nfrom sunholo.utils import ConfigManager\n\nconfig = ConfigManager('my-agent')\n\n# Process a file directly\nresult = direct_file_to_embed(\n \"document.pdf\",\n embed_prefix=\"doc\",\n metadata={\"source\": \"user_upload\"},\n vectorstore=config.vacConfig(\"vectorstore\")\n)\n```\n\n### Vertex AI with Memory Tools\n\n```python\nfrom sunholo.vertex import get_vertex_memories\nfrom sunholo.utils import ConfigManager\n\nconfig = ConfigManager('my-agent')\n\n# Get Vertex AI memory configuration\nmemory_config = get_vertex_memories(config)\n\n# Use with Vertex AI\nif memory_config:\n print(f\"Memory tools configured: {memory_config}\")\n```\n\n### Streaming Response with Flask\n\n```python\nfrom sunholo.agents import send_to_qa\nfrom flask import Response, request\n\n@app.route('/vac/streaming/<vac_name>', methods=['POST'])\ndef streaming_endpoint(vac_name):\n question = request.json.get('user_input')\n \n def generate():\n # Stream responses from the QA system\n response = send_to_qa(\n question, \n vac_name=vac_name,\n stream=True\n )\n if hasattr(response, '__iter__'):\n for chunk in response:\n yield f\"data: {chunk}\\n\\n\"\n else:\n yield f\"data: {response}\\n\\n\"\n \n return Response(generate(), content_type='text/event-stream')\n```\n\n### Discovery Engine Integration\n\n```python\nfrom sunholo.discovery_engine import DiscoveryEngineClient\n\n# Initialize client\nclient = DiscoveryEngineClient(\n project_id='my-project',\n data_store_id='my-datastore'\n)\n\n# Search documents\nresults = client.search(\"What is Vertex AI?\")\nfor result in results:\n print(f\"Content: {result.chunk.content}\")\n print(f\"Score: {result.relevance_score}\")\n```\n\n## \ud83e\uddea Testing\n\n```bash\n# Run all tests\npytest tests/\n\n# Run specific test file\npytest tests/test_config.py\n\n# Run with coverage\npytest --cov=src/sunholo tests/\n\n# Run async tests\npytest tests/test_async_genai2.py\n```\n\n## \ud83d\udcda Documentation\n\n- \ud83d\udcd6 **Full Documentation**: https://dev.sunholo.com/\n- \ud83c\udf93 **Tutorials**: https://dev.sunholo.com/docs/howto/\n- \ud83e\udd16 **VAC Examples**: https://github.com/sunholo-data/vacs-public\n- \ud83c\udfa7 **Audio Overview**: [Listen to the NotebookLM podcast](https://drive.google.com/file/d/1GvwRmiYDjPjN2hXQ8plhnVDByu6TmgCQ/view?usp=drive_link)\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See our [Contributing Guidelines](CONTRIBUTING.md).\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcdc License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE.txt) file for details.\n\n```\nCopyright [2024] [Holosun ApS]\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n```\n\n## \ud83d\ude4f Support\n\n- \ud83d\udce7 Email: multivac@sunholo.com\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/sunholo-data/sunholo-py/issues)\n- \ud83d\udcac Discussions: [GitHub Discussions](https://github.com/sunholo-data/sunholo-py/discussions)\n- \ud83d\udcd6 Documentation: https://dev.sunholo.com/\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "AI DevOps - a package to help deploy GenAI to the Cloud.",
"version": "0.144.12",
"project_urls": {
"Download": "https://github.com/sunholo-data/sunholo-py/archive/refs/tags/v0.118.0.tar.gz",
"Homepage": "https://github.com/sunholo-data/sunholo-py"
},
"split_keywords": [
"llms",
" devops",
" google_cloud_platform"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dbbf9fc719b765f76a0e8735311eda3c528ba2647728768111b9ac00678032ed",
"md5": "a63ba01112043410b2ccf66c388780f4",
"sha256": "64f0695d8445c3980bcf2fe9d749053dbb8d7c239ece3fb61186c644450be6cf"
},
"downloads": -1,
"filename": "sunholo-0.144.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a63ba01112043410b2ccf66c388780f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 323758,
"upload_time": "2025-09-13T18:24:51",
"upload_time_iso_8601": "2025-09-13T18:24:51.497926Z",
"url": "https://files.pythonhosted.org/packages/db/bf/9fc719b765f76a0e8735311eda3c528ba2647728768111b9ac00678032ed/sunholo-0.144.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cabb01ee0b6159d7583db350edf769a83cd6f4aafcb0bafd1d4786d7dfcb8c98",
"md5": "57808f7f2f96094efa9dbc283cd818f2",
"sha256": "41c414c63406c925070bf4c71a2a68888db594f47a362e6f79f9c3f35832a2d5"
},
"downloads": -1,
"filename": "sunholo-0.144.12.tar.gz",
"has_sig": false,
"md5_digest": "57808f7f2f96094efa9dbc283cd818f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 267318,
"upload_time": "2025-09-13T18:24:54",
"upload_time_iso_8601": "2025-09-13T18:24:54.123682Z",
"url": "https://files.pythonhosted.org/packages/ca/bb/01ee0b6159d7583db350edf769a83cd6f4aafcb0bafd1d4786d7dfcb8c98/sunholo-0.144.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-13 18:24:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sunholo-data",
"github_project": "sunholo-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sunholo"
}
JSON
