hevo-assistant 0.5.0

Chat-to-Action CLI for Hevo Data pipelines with RAG-powered assistance

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 - Europe
• in - India
• apac - 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

1. Verify your Hevo API key and secret are correct
2. Check that your API key has the required permissions
3. Ensure you've selected the correct region

LLM errors

1. Verify your LLM API key is valid
2. For Ollama, ensure the service is running (ollama serve)
3. Check that the model name is correct

Pinecone errors

1. Verify your Pinecone API key is correct
2. 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.