Sunholo Python Library
🚀 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 - a fast, modern Python package manager:
# 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
# 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
- Initialize a new project:
sunholo init my-ai-agent
cd my-ai-agent
- Configure your AI agent:
Edit
config/vac_config.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"
- Chat with your agent locally:
sunholo vac chat my-agent
- Run your agent as a local Flask app:
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
# 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
# Upgrade
uv tool upgrade sunholo
# List installed
uv tool list
# Uninstall
uv tool uninstall sunholo
Development Setup
# 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:
# 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
# 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
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
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
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
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
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
# 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
🤝 Contributing
We welcome contributions! See our Contributing Guidelines.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
📜 License
This project is licensed under the Apache License 2.0 - see the LICENSE 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
- 💬 Discussions: GitHub Discussions
- 📖 Documentation: https://dev.sunholo.com/
1 maintainer
Release files for sunholo 0.146.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sunholo-0.146.1.tar.gz | 335.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sunholo-0.146.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 739.7 kB
Release files / sunholo-0.146.1.tar.gz
| Download URL | sunholo-0.146.1.tar.gz |
|---|---|
| Size | 335.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca32a9618e3e0a883c4959e910a2370827b44ca7ed90b77090c573d8466f433d
|
|
BLAKE2b-256 checksum How to use checksums |
b3e9cc985a213083c95cf9fc3f22bf7cc55baf8c4618b06da44beb1ee60f9bc1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / sunholo-0.146.1-py3-none-any.whl
| Download URL | sunholo-0.146.1-py3-none-any.whl |
|---|---|
| Size | 404.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0e44826dbae392c25c1a617682e66cb970d74e94e91a045b9478c3c744c75c0b
|
|
BLAKE2b-256 checksum How to use checksums |
2ab597c4c56cbb6577f3aa9058c39bfc173be85763802be2bc13d687f401c99d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
