heysol-api-client 1.3.0
A comprehensive Python client for the HeySol API with MCP protocol support, built by Dexter Hadley, MD/PhD
License: MIT
Requires Python: >=3.8
Keywords: heysol, api-client, mcp, memory-management, healthcare, clinical-trials, oncology, python

# 🚀 HeySol API Client

[![PyPI version](https://badge.fury.io/py/heysol-api-client.svg)](https://pypi.org/project/heysol-api-client/)
[![Python versions](https://img.shields.io/pypi/pyversions/heysol-api-client.svg)](https://pypi.org/project/heysol-api-client/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

Built by [Dexter Hadley, MD/PhD](mailto:iDrDex@HadleyLab.org) 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

[![Code Quality](https://img.shields.io/badge/Code%20Quality-A%2B-green.svg)](https://github.com/HadleyLab/heysol-api-client)
[![Type Checked](https://img.shields.io/badge/Type%20Checked-100%25-blue.svg)](#)
[![Linting](https://img.shields.io/badge/Linting-Passed-success.svg)](#)
[![Tests](https://img.shields.io/badge/Tests-Passing-brightgreen.svg)](#)

**✅ 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

```bash
pip install heysol-api-client
```

For development (from source):
```bash
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](https://core.heysol.ai/settings/api)
2. **Set environment variable**:
   ```bash
   export HEYSOL_API_KEY="your-api-key-here"
   ```
3. **Try the quick start**:
   ```bash
   python quick_start.py
   ```

### Basic Usage

```python
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

```bash
# 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
```

## ⚙️ Configuration

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

### Environment Variables (Recommended)
```bash
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:
```bash
# .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`:
```bash
# .env with multiple instances
# research@clinicaltrials.gov
HEYSOL_API_KEY=your-research-key

# backup@archive.com
HEYSOL_API_KEY=your-backup-key
```

### Programmatic Configuration
```python
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
```bash
# 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
```

## 📖 API Reference

### Memory Operations
```python
# 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
```python
# 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
```python
# 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
```python
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`](quick_start.ipynb)** - Complete setup in 5 minutes
- **[`examples/api_endpoints_demo.ipynb`](examples/api_endpoints_demo.ipynb)** - Core API operations

**Build Skills - Intermediate:**
- **[`examples/client_types_demo.ipynb`](examples/client_types_demo.ipynb)** - Choose the right client
- **[`examples/error_handling_demo.ipynb`](examples/error_handling_demo.ipynb)** - Production-ready patterns

**Master Advanced Features:**
- **[`examples/comprehensive_client_demo.ipynb`](examples/comprehensive_client_demo.ipynb)** - Full capabilities showcase
- **[`examples/log_management_demo.ipynb`](examples/log_management_demo.ipynb)** - Monitoring and optimization

### 📖 Documentation
- **[API Documentation](docs/API_DOCUMENTATION.md)** - Complete reference
- **[Testing Report](docs/TESTING_REPORT.md)** - Quality assurance details
- **[API vs MCP Analysis](docs/API_VS_MCP_ANALYSIS.md)** - Protocol comparison

### 🎯 Real-World Use Cases

**Clinical Research:**
```python
# 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:**
```python
# 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

```bash
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

```bash
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](CHANGELOG.md) for detailed release notes.*

## License

MIT License - see [LICENSE](LICENSE) file for details.

## 💬 Support & Contributing

**Get Help:**
- 📧 **[Email Support](mailto:iDrDex@HadleyLab.org)** - Direct access to the maintainer
- 🐛 **[GitHub Issues](https://github.com/HadleyLab/heysol-api-client/issues)** - Bug reports and feature requests
- 📖 **[Full Documentation](https://docs.heysol.ai/api-reference)** - Comprehensive guides and API reference

**Built by:** [Dexter Hadley, MD/PhD](mailto:iDrDex@HadleyLab.org) - Clinical researcher and AI developer