heysol-api-client 0.9.1

A comprehensive Python client for the HeySol API with MCP protocol support

HeySol API Client

A comprehensive Python client for the HeySol API with MCP protocol support, memory management, and CLI tools.

Version 0.9.1 - Pre-release with full API coverage.

Features

• 🚀 Full API Coverage: Complete HeySol API endpoints with client-side status filtering
• 🔐 Authentication: API key and Bearer token support
• 📝 Memory Management: Ingest, search, and manage memory spaces
• 🛡️ Error Handling: Robust exception hierarchy with retries
• 📊 Rate Limiting: Built-in throttling and rate limiting
• 🖥️ CLI Interface: Command-line tools for all operations
• 📚 Type Hints: Full type annotation support
• 🧪 Well Tested: Comprehensive test suite with 95%+ coverage
• 📖 Rich Documentation: Interactive notebooks and examples

Installation

pip install heysol-api-client

For development (from source):

git clone https://github.com/heysol/heysol-python-client.git
cd heysol_api_client
pip install -e ".[dev]"

Quick Start

1. Get your API key from HeySol Core
2. Set environment variable:

   export HEYSOL_API_KEY="your-api-key-here"
   

3. Try the quick start:

   python quick_start.py
   

Basic Usage

from heysol import HeySolClient

# Initialize client
client = HeySolClient(api_key="your-api-key")

# Create a space
space_id = client.create_space("Research", "Clinical data")

# Ingest data
client.ingest("New treatment shows promise", space_id=space_id)

# Search
results = client.search("treatment", space_ids=[space_id])
print(results["episodes"])

client.close()

CLI Usage

# Profile
heysol-client profile get

# Spaces
heysol-client spaces list
heysol-client spaces create "My Space" --description "Data space"

# Memory operations
heysol-client memory ingest "Clinical data" --space-id <space-id>
heysol-client memory search "cancer research" --limit 10

# Logs
heysol-client logs list --status success
heysol-client logs delete-by-source "source-name" --confirm

Configuration

⚠️ IMPORTANT: API keys must be loaded from environment variables only. Never store them in config files.

Environment Variables (Recommended)

Set environment variables for secure configuration:

export HEYSOL_API_KEY="your-key"
export HEYSOL_BASE_URL="https://core.heysol.ai/api/v1"
export HEYSOL_SOURCE="my-app"

.env File Support

Alternatively, create a .env file in your project root:

# .env
HEYSOL_API_KEY=your-key-here
HEYSOL_BASE_URL=https://core.heysol.ai/api/v1
HEYSOL_SOURCE=my-app

Strict Loading Policy

• ✅ Allowed: Environment variables, .env files
• ❌ Not Allowed: JSON config files, hardcoded keys
• 🔒 Security: HeySolConfig.from_env() only reads from environment variables
• 🚫 No Fallback: Config files are never loaded automatically

Programmatic Configuration

from heysol import HeySolClient, HeySolConfig

# Load from environment (recommended)
client = HeySolClient()  # Uses HeySolConfig.from_env() automatically

# Or load explicitly
config = HeySolConfig.from_env()
client = HeySolClient(config=config)

API Reference

Core Methods

Memory Operations:

• ingest(message, space_id=None) - Add data to memory
• search(query, space_ids=None, limit=10) - Search memories
• search_knowledge_graph(query, space_id=None) - Graph search

Space Operations:

• get_spaces() - List all spaces
• create_space(name, description="") - Create new space
• update_space(space_id, name=None, description=None) - Update space
• delete_space(space_id, confirm=False) - Delete space

Log Operations:

• get_ingestion_logs(space_id=None, limit=100) - Get logs
• check_ingestion_status(run_id=None) - Check status

Webhook Operations:

• register_webhook(url, events=None, secret="") - Create webhook
• list_webhooks(space_id=None) - List webhooks

Error Handling

from heysol import HeySolError, AuthenticationError

try:
    result = client.search("query")
except AuthenticationError:
    print("Check your API key")
except HeySolError as e:
    print(f"API error: {e}")

Examples & Documentation

Interactive Notebooks

• 📚 quick_start.ipynb - Python API walkthrough
• 📚 examples/api_endpoints_demo.ipynb - API endpoints demonstration
• 📚 examples/client_types_demo.ipynb - Client types comparison
• 📚 examples/comprehensive_client_demo.ipynb - Full client capabilities
• 📚 examples/error_handling_demo.ipynb - Error handling patterns
• 📚 examples/integration_test_demo.ipynb - Integration testing
• 📚 examples/log_management_demo.ipynb - Log management

Documentation

• 📖 API Documentation - Complete API reference
• 📖 Testing Report - Comprehensive testing documentation
• 📖 API vs MCP Analysis - Protocol comparison guide

Testing

pytest                    # Run all tests
pytest --cov=heysol      # With coverage
pytest -m "unit"         # Unit tests only

Development

git clone https://github.com/heysol/heysol-python-client.git
cd heysol-python-client
pip install -e ".[dev]"
pre-commit install

Changelog

v0.9.1 (2025-09-24)

• 🚀 Pre-release with full API coverage and stability
• 📦 PyPI Publication of 0.9.1 version
• 🔧 Version alignment across all configuration files
• 📖 Documentation updates with correct repository links

v0.9.0 (2025-09-23)

• ✨ Client-side status filtering for logs CLI commands
• 📚 6 new comprehensive example notebooks in examples/ directory
• 🔧 Enhanced CLI with improved log management capabilities
• 🧪 95%+ test coverage with comprehensive testing suite
• 📦 PyPI publication ready for production use
• 🏗️ Pre-1.0 release with stable API

v0.8.0 (2025-09-22)

• 🚀 Full HeySol API coverage with MCP protocol support
• 🖥️ Complete CLI interface for all operations
• 📝 Memory space management with search and ingestion
• 🛡️ Robust error handling with validation
• 📊 Rate limiting and performance optimizations

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 📖 Docs: https://docs.heysol.ai/api-reference
• 🐛 Issues: https://github.com/heysol/heysol-python-client/issues
• 👤 Author: iDrDex (HadleyLab)