Hevo Assistant
A chat-to-action CLI tool for managing Hevo Data pipelines using natural language. Ask questions, check status, pause/resume pipelines, and more - all through conversation.
Features
- Natural Language Interface: Interact with your Hevo pipelines using plain English
- RAG-Powered Responses: Get accurate answers based on Hevo documentation
- Multiple LLM Providers: Choose between OpenAI, Anthropic Claude, or local Ollama
- Pipeline Management: List, pause, resume, and run pipelines
- Model & Workflow Support: Manage dbt models and workflows
- Secure Configuration: Credentials stored locally in
~/.hevo/ - Fast Installation: ~30 seconds (no heavy ML dependencies)
Installation
pip install hevo-assistant
That's it! Installation is fast because we use cloud services (Pinecone + OpenAI) instead of local ML models.
For Development
git clone https://github.com/Legolasan/hevo-app.git
cd hevo-app
pip install -e .
Optional: Local RAG (Heavy)
If you prefer to run embeddings locally (offline mode), install with:
pip install hevo-assistant[local-rag]
Note: This adds ~2GB of dependencies (PyTorch, sentence-transformers).
Quick Start
1. Setup Configuration
Run the interactive setup wizard:
hevo setup
You'll be prompted for:
- Hevo API credentials: Get from Hevo Dashboard > Settings > API Keys
- LLM provider: Choose OpenAI, Anthropic, or Ollama
- LLM API key: Your provider's API key (not needed for Ollama)
- Pinecone API key: Get free at pinecone.io
2. Start Chatting
# Interactive chat mode
hevo chat
# Or ask a one-shot question
hevo ask "List my pipelines"
Usage Examples
# Check pipeline status
hevo ask "What's the status of my Salesforce pipeline?"
# List all pipelines
hevo ask "Show me all my pipelines"
# Pause a pipeline
hevo ask "Pause the MySQL pipeline"
# Resume a pipeline
hevo ask "Resume the MySQL pipeline"
# Run a pipeline now
hevo ask "Run the Salesforce pipeline now"
# Ask about Hevo features
hevo ask "How do I create a new destination?"
# List models
hevo ask "What models do I have?"
# Run a model
hevo ask "Run my revenue model"
Commands
| Command | Description |
|---|---|
hevo setup |
Interactive setup wizard |
hevo config show |
Show current configuration |
hevo chat |
Start interactive chat session |
hevo ask "query" |
Ask a one-shot question |
Configuration
Configuration is stored in ~/.hevo/config.json:
{
"hevo": {
"api_key": "your-api-key",
"api_secret": "your-api-secret",
"region": "us"
},
"llm": {
"provider": "openai",
"api_key": "sk-...",
"model": "gpt-4"
},
"rag": {
"backend": "pinecone",
"pinecone_api_key": "pc-...",
"pinecone_index": "hevo-docs"
}
}
Supported Regions
us- United States (default)eu- Europein- Indiaapac- Asia Pacific
Supported LLM Providers
| Provider | Models | Notes |
|---|---|---|
| OpenAI | gpt-4, gpt-4-turbo, gpt-3.5-turbo | Recommended for best results |
| Anthropic | claude-3-opus, claude-3-sonnet | Great for detailed explanations |
| Ollama | llama3, mistral, etc. | Local, free, no API key needed |
Available Actions
The assistant can execute these actions on your behalf:
Pipeline Actions
- List all pipelines
- Get pipeline status
- Pause a pipeline
- Resume a pipeline
- Run a pipeline immediately
Object Actions
- List objects in a pipeline
- Skip a failed object
- Restart an object
Model Actions
- List all models
- Run a model
Workflow Actions
- List all workflows
- Run a workflow
Destination Actions
- List all destinations
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ hevo-assistant CLI │
├─────────────────────────────────────────────────────────────────┤
│ User Query ──► Intent Parser ──► RAG Context ──► LLM ──► Action│
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Pinecone OpenAI Hevo API │
│ (Vector DB) (Embeddings) (Actions) │
└─────────────────────────────────────────────────────────────────┘
Requirements
- Python 3.10+
- Hevo Data account with API access
- LLM API key (OpenAI, Anthropic) or local Ollama installation
- Pinecone API key (free tier available at pinecone.io)
Troubleshooting
"Configuration incomplete" error
Run hevo setup to configure your API credentials.
API authentication errors
- Verify your Hevo API key and secret are correct
- Check that your API key has the required permissions
- Ensure you've selected the correct region
LLM errors
- Verify your LLM API key is valid
- For Ollama, ensure the service is running (
ollama serve) - Check that the model name is correct
Pinecone errors
- Verify your Pinecone API key is correct
- Ensure the index "hevo-docs" exists and is accessible
Development
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black src/
License
MIT License - see LICENSE file for details.
Contributing
Contributions welcome! Please read the contributing guidelines first.
Metadata
Release files for hevo-assistant 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hevo_assistant-0.10.0.tar.gz | 77.5 kB | Without provenance | Details for hevo_assistant-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hevo_assistant-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for hevo_assistant-0.10.0-py3-none-any.whl |
Total release size: 170.2 kB
Release files / hevo_assistant-0.10.0.tar.gz
| Download URL | hevo_assistant-0.10.0.tar.gz |
|---|---|
| Size | 77.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a45c09ec6d1ac0643d67a0af0578857a1924d37a7e5671e7c6a09a3eb4894022
|
|
BLAKE2b-256 checksum How to use checksums |
2af42a8fd6e5f6a81e2c2d0d76dee2da5f3f2e91b15c5da66b3adfc4365dd68f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / hevo_assistant-0.10.0-py3-none-any.whl
| Download URL | hevo_assistant-0.10.0-py3-none-any.whl |
|---|---|
| Size | 92.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5fab296c33ee02d6aee7aba7a2a614cedd5f1c75e92da2d404038b5381e10fcb
|
|
BLAKE2b-256 checksum How to use checksums |
7732f63d4f2ef83e25f5a038d154ad998f9fa25a50b384a797d241be3bcc7842
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for hevo-assistant 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.