heysol-api-client 1.3.0

A comprehensive Python client for the HeySol API with MCP protocol support, built by Dexter Hadley, MD/PhD

🚀 HeySol API Client

Seamlessly integrate HeySol's powerful memory and AI capabilities into your Python applications.

Built by Dexter Hadley, MD/PhD for clinical research and AI-powered healthcare applications.

Version 1.3.0 - Production-ready with enterprise-grade code quality and comprehensive CLI tools.

🏆 Code Quality Status

✅ Enterprise-Grade Quality: 100% compliance with PEP 8, PEP 257, PEP 484 standards. All code passes comprehensive automated validation including mypy type checking, ruff linting, black formatting, and isort import organization.

🔥 Why HeySol API Client?

Transform how you work with AI memory and knowledge management:

• 🔬 Clinical Research: Manage vast amounts of medical literature, patient data, and research findings
• 🏥 Healthcare AI: Build intelligent applications that remember context across sessions
• 📊 Data Science: Create persistent memory spaces for long-running analysis projects
• 🤖 AI Agents: Enable context-aware agents that learn and adapt over time

Real-world impact: From managing clinical trial data to building AI assistants that remember patient preferences, HeySol API Client bridges the gap between powerful AI capabilities and practical application development.

Installation

pip install heysol-api-client

For development (from source):

git clone https://github.com/HadleyLab/heysol-api-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

# Registry Management (NEW!)
heysol registry list                                    # List all registered instances
heysol registry show [e-mail]              # Show instance details
heysol registry use [e-mail]               # Set active instance
heysol registry register                               # Load instances from .env file

# Multi-Instance Memory Operations (NEW!)
heysol memory move [e-mail] [e-mail] --confirm
heysol memory copy [e-mail] [e-mail] --confirm
heysol memory search [e-mail] "cancer research" --limit 10
heysol memory ingest [e-mail] "Clinical data" --space-id <space-id>

# Traditional Operations
heysol profile get
heysol spaces list
heysol spaces create "My Space" --description "Data space"
heysol logs list --status success
heysol logs delete-by-source "source-name" --confirm

⚙️ Configuration

🔒 Security First: API keys are loaded from environment variables only. Never store them in config files.

Environment Variables (Recommended)

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

.env File Support

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

Multi-Instance Setup

For multiple HeySol instances, use email-based identifiers in your .env:

# .env with multiple instances
# [e-mail]
HEYSOL_API_KEY=your-research-key

# [e-mail]
HEYSOL_API_KEY=your-backup-key

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)

🏗️ Multi-Instance Registry

Manage multiple HeySol accounts effortlessly with human-readable email identifiers.

Registry Commands

# List all registered instances
heysol registry list

# Set active instance
heysol registry use [e-mail]

# Cross-instance operations
heysol memory copy [e-mail] [e-mail] --confirm
heysol memory search [e-mail] "cancer treatment" --limit 20

📖 API Reference

Memory Operations

# Ingest research data with metadata
client.ingest(
    "Phase III trial shows 45% improvement in progression-free survival",
    space_id=space_id,
    metadata={"source": "clinicaltrials.gov", "date": "2024-01-15"}
)

# Semantic search across spaces
results = client.search(
    "cancer immunotherapy treatments",
    space_ids=[space_id],
    limit=20
)

# Knowledge graph exploration
graph_results = client.search_knowledge_graph(
    "PD-1 inhibitors",
    space_id=space_id
)

Space Management

# Create organized spaces for your data
clinical_trials = client.create_space("Active Trials", "Ongoing clinical studies")
literature = client.create_space("Literature Review", "Published research papers")

# List and manage spaces
spaces = client.get_spaces()
for space in spaces:
    print(f"{space['name']}: {space['description']}")

Log Management

# Monitor your data operations
logs = client.get_ingestion_logs(space_id=space_id, limit=50)

# Check operation status
status = client.check_ingestion_status(run_id="recent-run-id")
print(f"Status: {status['state']}")

Error Handling

from heysol import HeySolError, AuthenticationError, RateLimitError

try:
    results = client.search("cancer treatment")
    print(f"Found {len(results['episodes'])} results")
except AuthenticationError:
    print("❌ Invalid API key - check your configuration")
except RateLimitError:
    print("⏱️ Rate limit exceeded - retry after delay")
except HeySolError as e:
    print(f"❌ API error: {e}")

🎓 Examples & Learning Resources

📚 Interactive Learning Path

Start Here - Beginner:

• quick_start.ipynb - Complete setup in 5 minutes
• examples/api_endpoints_demo.ipynb - Core API operations

Build Skills - Intermediate:

• examples/client_types_demo.ipynb - Choose the right client
• examples/error_handling_demo.ipynb - Production-ready patterns

Master Advanced Features:

• examples/comprehensive_client_demo.ipynb - Full capabilities showcase
• examples/log_management_demo.ipynb - Monitoring and optimization

📖 Documentation

• API Documentation - Complete reference
• Testing Report - Quality assurance details
• API vs MCP Analysis - Protocol comparison

🎯 Real-World Use Cases

Clinical Research:

# Organize clinical trial data
trials_space = client.create_space("Active Trials", "Ongoing studies")
client.ingest("Phase II results: 78% response rate", space_id=trials_space)

# Literature review and analysis
review_space = client.create_space("Literature", "Published research")
client.ingest("Meta-analysis shows significant survival benefit", space_id=review_space)

# Cross-reference findings
results = client.search("survival benefit", space_ids=[trials_space, review_space])

Healthcare AI:

# Patient context management
patient_space = client.create_space("Patient Records", "Medical history")
client.ingest("Patient reports improved symptoms", space_id=patient_space)

# Treatment recommendations
recommendations = client.search("similar cases", space_ids=[patient_space])

Testing

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

🧪 Quality Assurance

✅ Comprehensive Test Coverage: Unit tests, integration tests, and end-to-end validation ✅ Code Quality Gates: All code passes automated validation (mypy, ruff, black, isort) ✅ Standards Compliance: 100% PEP 8, PEP 257, PEP 484 compliance ✅ Performance Validation: Optimized for speed with minimal overhead

Development

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

📋 Recent Updates

v1.3.0 (Current)

• 🏆 Enterprise Code Quality - 100% compliance with PEP 8, PEP 257, PEP 484 standards
• 🔧 Automated Quality Enforcement - mypy type checking, ruff linting, black formatting, isort organization
• 🧪 Comprehensive Testing - Full test coverage with unit, integration, and CLI validation tests
• 📊 Quality Metrics - 100% success rates across all validation categories
• 🏗️ Multi-Instance Registry - Manage multiple HeySol accounts with email identifiers
• 🔄 Cross-Instance Operations - Copy and move data between instances
• 🖥️ Enhanced CLI - Complete command-line interface for all operations
• 📚 Interactive Examples - Comprehensive notebooks and demos

Previous releases focused on:

• Complete API coverage with MCP protocol support
• Robust error handling and rate limiting
• Memory space management and search capabilities
• Production-ready testing and documentation

See CHANGELOG.md for detailed release notes.

License

MIT License - see LICENSE file for details.

💬 Support & Contributing

Get Help:

• 📧 Email Support - Direct access to the maintainer
• 🐛 GitHub Issues - Bug reports and feature requests
• 📖 Full Documentation - Comprehensive guides and API reference

Built by: Dexter Hadley, MD/PhD - Clinical researcher and AI developer