Metadata-Version: 2.4
Name: hacs-persistence
Version: 0.3.1
Summary: Database and vector store persistence adapters for HACS
Project-URL: Homepage, https://github.com/solanovisitor/hacs-ai
Project-URL: Documentation, https://github.com/solanovisitor/hacs-ai/blob/main/docs/
Project-URL: Repository, https://github.com/solanovisitor/hacs-ai
Project-URL: Issues, https://github.com/solanovisitor/hacs-ai/issues
Project-URL: Changelog, https://github.com/solanovisitor/hacs-ai/blob/main/CHANGELOG.md
Author-email: Solano Nocetti <solanovisitor@gmail.com>
Maintainer-email: Solano Nocetti <solanovisitor@gmail.com>
License: MIT
Keywords: ai,database,fhir,healthcare,persistence,vector-store
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: hacs-core>=0.3.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: all
Requires-Dist: pgvector>=0.2.4; extra == 'all'
Requires-Dist: pinecone>=7.3.0; extra == 'all'
Requires-Dist: psycopg[async,binary]>=3.2.9; extra == 'all'
Requires-Dist: qdrant-client>=1.15.1; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: pgvector
Requires-Dist: pgvector>=0.2.4; extra == 'pgvector'
Provides-Extra: pinecone
Requires-Dist: pinecone>=7.3.0; extra == 'pinecone'
Provides-Extra: postgresql
Requires-Dist: psycopg[async,binary]>=3.2.9; extra == 'postgresql'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.15.1; extra == 'qdrant'
Description-Content-Type: text/markdown

# HACS Persistence

**PostgreSQL + pgvector persistence for healthcare data storage**

Database and vector storage adapters optimized for healthcare AI applications.

## 🗄️ **Database Support**

### **PostgreSQL with pgvector**
Primary storage solution for healthcare data:

- **Relational Data** - Patient records, observations, clinical data
- **Vector Storage** - Clinical embeddings via pgvector extension
- **Schema Management** - Automated migrations and versioning
- **Healthcare Compliance** - HIPAA-aware design patterns

## 🏥 **Healthcare Schema**

Optimized database tables for clinical workflows:

```sql
-- Core healthcare tables
patients              -- Patient demographics and clinical context
observations         -- Clinical measurements and findings
actors              -- Healthcare providers with role-based permissions
memory_blocks       -- AI agent episodic/procedural memory
evidence_items     -- Clinical guidelines and research
knowledge_base     -- Structured clinical knowledge

-- Vector storage for AI operations
patient_vectors     -- Patient data embeddings
clinical_vectors    -- Clinical note embeddings
memory_vectors      -- Memory content embeddings
```

## 📦 **Installation**

```bash
pip install hacs-persistence
```

## 🚀 **Quick Start**

### **Setup via HACS**
```bash
# Automatic setup with migrations
python setup.py --mode local

# Database runs on localhost:5432
# Automatic pgvector extension installation
```

### **Direct Usage**
```python
from hacs_persistence import Adapter
from hacs_core import Patient

# Connect to healthcare database
adapter = Adapter(
    database_url="postgresql://hacs:password@localhost:5432/hacs"
)

# Store patient record
patient = Patient(
    full_name="Maria Rodriguez",
    birth_date="1985-03-15",
    gender="female"
)

# Save with automatic validation
saved_patient = adapter.save_resource(patient)
print(f"Saved patient: {saved_patient.id}")
```

## 🔧 **Configuration**

### **Environment Variables**
```bash
# Primary database connection
DATABASE_URL=postgresql://hacs:password@localhost:5432/hacs

# Vector store configuration (uses pgvector by default)
VECTOR_STORE=pgvector

# Optional: External PostgreSQL for production
DATABASE_URL=postgresql://hacs:secure_password@prod-db:5432/hacs_production
```

### **Migration Management**
```bash
# Run database migrations
python -m hacs_persistence.migrations $DATABASE_URL

# Check migration status
python -c "from hacs_persistence import get_migration_status; print(get_migration_status())"
```

## 📊 **Performance**

- **Resource Operations**: <50ms for standard CRUD
- **Vector Queries**: <100ms for similarity search
- **Batch Operations**: 1000+ records per second
- **Memory Footprint**: Minimal overhead

## 🔐 **Security Features**

- **Connection Encryption** - SSL/TLS support
- **Role-based Access** - Healthcare provider permissions
- **Audit Trails** - Complete operation logging
- **Data Isolation** - Organization-specific schemas

## 🛠️ **Advanced Usage**

### **Vector Operations**
```python
# Store clinical embedding
adapter.store_vector(
    resource_id="patient_123",
    embedding=[0.1, 0.2, ...],  # Clinical text embedding
    metadata={"type": "patient", "department": "cardiology"}
)

# Similarity search
similar_patients = adapter.vector_search(
    query_embedding=[0.1, 0.2, ...],
    resource_type="patient",
    top_k=5
)
```

### **Batch Operations**
```python
# Bulk insert for large datasets
patients = [Patient(...) for _ in range(1000)]
results = adapter.bulk_save(patients)
```

## 📄 **License**

Apache-2.0 License - see [LICENSE](../../LICENSE) for details.