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.
✅ 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.
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.
pip install heysol-api-clientFor development (from source):
git clone https://github.com/HadleyLab/heysol-api-client.git
cd heysol_api_client
pip install -e ".[dev]"- Get your API key from HeySol Core
- Set environment variable:
export HEYSOL_API_KEY="your-api-key-here"
- Try the quick start:
python quick_start.py
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()# Registry Management (NEW!)
heysol registry list # List all registered instances
heysol registry show iDrDex@MammoChat.com # Show instance details
heysol registry use iDrDex@MammoChat.com # Set active instance
heysol registry register # Load instances from .env file
# Multi-Instance Memory Operations (NEW!)
heysol memory move iDrDex@gmail.com HadleyLaboratory@gmail.com --confirm
heysol memory copy iDrDex@MammoChat.com iDrDex@gmail.com --confirm
heysol memory search iDrDex@MammoChat.com "cancer research" --limit 10
heysol memory ingest iDrDex@MammoChat.com "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🔒 Security First: API keys are loaded from environment variables only. Never store them in config files.
export HEYSOL_API_KEY="your-key"
export HEYSOL_BASE_URL="https://core.heysol.ai/api/v1"
export HEYSOL_SOURCE="my-app"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-appFor multiple HeySol instances, use email-based identifiers in your .env:
# .env with multiple instances
# research@clinicaltrials.gov
HEYSOL_API_KEY=your-research-key
# backup@archive.com
HEYSOL_API_KEY=your-backup-keyfrom 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)Manage multiple HeySol accounts effortlessly with human-readable email identifiers.
# List all registered instances
heysol registry list
# Set active instance
heysol registry use research@clinicaltrials.gov
# Cross-instance operations
heysol memory copy research@trials.gov backup@archive.com --confirm
heysol memory search research@trials.gov "cancer treatment" --limit 20# 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
)# 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']}")# 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']}")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}")Start Here - Beginner:
quick_start.ipynb- Complete setup in 5 minutesexamples/api_endpoints_demo.ipynb- Core API operations
Build Skills - Intermediate:
examples/client_types_demo.ipynb- Choose the right clientexamples/error_handling_demo.ipynb- Production-ready patterns
Master Advanced Features:
examples/comprehensive_client_demo.ipynb- Full capabilities showcaseexamples/log_management_demo.ipynb- Monitoring and optimization
- API Documentation - Complete reference
- Testing Report - Quality assurance details
- API vs MCP Analysis - Protocol comparison
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])pytest # Run all tests
pytest --cov=heysol # With coverage
pytest -m "unit" # Unit tests only✅ 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
git clone https://github.com/HadleyLab/heysol-api-client.git
cd heysol-api-client
pip install -e ".[dev]"
pre-commit installv1.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.
MIT License - see LICENSE file for details.
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