# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "hacs-persistence",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Solano Todeschini <solanovisitor@gmail.com>",
"keywords": "ai, database, fhir, healthcare, persistence, vector-store",
"author": null,
"author_email": "Solano Todeschini <solanovisitor@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/f6/0c/68f4d0c37475b595253ebcf2fa72186ae19cfc682705f5ae9cfffd000c81/hacs_persistence-0.4.3.tar.gz",
"platform": null,
"description": "# HACS Persistence\n\n**PostgreSQL + pgvector persistence for healthcare data storage**\n\nDatabase and vector storage adapters optimized for healthcare AI applications.\n\n## \ud83d\uddc4\ufe0f **Database Support**\n\n### **PostgreSQL with pgvector**\nPrimary storage solution for healthcare data:\n\n- **Relational Data** - Patient records, observations, clinical data\n- **Vector Storage** - Clinical embeddings via pgvector extension\n- **Schema Management** - Automated migrations and versioning\n- **Healthcare Compliance** - HIPAA-aware design patterns\n\n## \ud83c\udfe5 **Healthcare Schema**\n\nOptimized database tables for clinical workflows:\n\n```sql\n-- Core healthcare tables\npatients -- Patient demographics and clinical context\nobservations -- Clinical measurements and findings\nactors -- Healthcare providers with role-based permissions\nmemory_blocks -- AI agent episodic/procedural memory\nevidence_items -- Clinical guidelines and research\nknowledge_base -- Structured clinical knowledge\n\n-- Vector storage for AI operations\npatient_vectors -- Patient data embeddings\nclinical_vectors -- Clinical note embeddings\nmemory_vectors -- Memory content embeddings\n```\n\n## \ud83d\udce6 **Installation**\n\n```bash\npip install hacs-persistence\n```\n\n## \ud83d\ude80 **Quick Start**\n\n### **Setup via HACS**\n```bash\n# Automatic setup with migrations\npython setup.py --mode local\n\n# Database runs on localhost:5432\n# Automatic pgvector extension installation\n```\n\n### **Direct Usage**\n```python\nfrom hacs_persistence import Adapter\nfrom hacs_core import Patient\n\n# Connect to healthcare database\nadapter = Adapter(\n database_url=\"postgresql://hacs:password@localhost:5432/hacs\"\n)\n\n# Store patient record\npatient = Patient(\n full_name=\"Maria Rodriguez\",\n birth_date=\"1985-03-15\",\n gender=\"female\"\n)\n\n# Save with automatic validation\nsaved_patient = adapter.save_resource(patient)\nprint(f\"Saved patient: {saved_patient.id}\")\n```\n\n## \ud83d\udd27 **Configuration**\n\n### **Environment Variables**\n```bash\n# Primary database connection\nDATABASE_URL=postgresql://hacs:password@localhost:5432/hacs\n\n# Vector store configuration (uses pgvector by default)\nVECTOR_STORE=pgvector\n\n# Optional: External PostgreSQL for production\nDATABASE_URL=postgresql://hacs:secure_password@prod-db:5432/hacs_production\n```\n\n### **Migration Management**\n```bash\n# Run database migrations\npython -m hacs_persistence.migrations $DATABASE_URL\n\n# Check migration status\npython -c \"from hacs_persistence import get_migration_status; print(get_migration_status())\"\n```\n\n## \ud83d\udcca **Performance**\n\n- **Resource Operations**: <50ms for standard CRUD\n- **Vector Queries**: <100ms for similarity search\n- **Batch Operations**: 1000+ records per second\n- **Memory Footprint**: Minimal overhead\n\n## \ud83d\udd10 **Security Features**\n\n- **Connection Encryption** - SSL/TLS support\n- **Role-based Access** - Healthcare provider permissions\n- **Audit Trails** - Complete operation logging\n- **Data Isolation** - Organization-specific schemas\n\n## \ud83d\udee0\ufe0f **Advanced Usage**\n\n### **Vector Operations**\n```python\n# Store clinical embedding\nadapter.store_vector(\n resource_id=\"patient_123\",\n embedding=[0.1, 0.2, ...], # Clinical text embedding\n metadata={\"type\": \"patient\", \"department\": \"cardiology\"}\n)\n\n# Similarity search\nsimilar_patients = adapter.vector_search(\n query_embedding=[0.1, 0.2, ...],\n resource_type=\"patient\",\n top_k=5\n)\n```\n\n### **Batch Operations**\n```python\n# Bulk insert for large datasets\npatients = [Patient(...) for _ in range(1000)]\nresults = adapter.bulk_save(patients)\n```\n\n## \ud83d\udcc4 **License**\n\nApache-2.0 License - see [LICENSE](../../LICENSE) for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "Database and vector store persistence adapters for HACS",
"version": "0.4.3",
"project_urls": {
"Changelog": "https://github.com/solanovisitor/hacs-ai/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/solanovisitor/hacs-ai/blob/main/docs/",
"Homepage": "https://github.com/solanovisitor/hacs-ai",
"Issues": "https://github.com/solanovisitor/hacs-ai/issues",
"Repository": "https://github.com/solanovisitor/hacs-ai"
},
"split_keywords": [
"ai",
" database",
" fhir",
" healthcare",
" persistence",
" vector-store"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "13f9f4e51a7c6c7b55da6a1c4fa9fee55eb096300a6448e13b97be0e475de6d7",
"md5": "8be961500151aa7f6a0577b0632833f0",
"sha256": "616f05db6c3fdf4c3c1d23f09a4835ce7fde4ec80fc2c2637af4bbc904fc4671"
},
"downloads": -1,
"filename": "hacs_persistence-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8be961500151aa7f6a0577b0632833f0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 35826,
"upload_time": "2025-08-12T14:27:50",
"upload_time_iso_8601": "2025-08-12T14:27:50.614250Z",
"url": "https://files.pythonhosted.org/packages/13/f9/f4e51a7c6c7b55da6a1c4fa9fee55eb096300a6448e13b97be0e475de6d7/hacs_persistence-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f60c68f4d0c37475b595253ebcf2fa72186ae19cfc682705f5ae9cfffd000c81",
"md5": "7263eecb1e790b3af370f42aa1455ebb",
"sha256": "ff31cee332a1a85662728de73fbbcffd8967038fb58a1fa49f69b274e8b199f8"
},
"downloads": -1,
"filename": "hacs_persistence-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "7263eecb1e790b3af370f42aa1455ebb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 30852,
"upload_time": "2025-08-12T14:28:00",
"upload_time_iso_8601": "2025-08-12T14:28:00.955113Z",
"url": "https://files.pythonhosted.org/packages/f6/0c/68f4d0c37475b595253ebcf2fa72186ae19cfc682705f5ae9cfffd000c81/hacs_persistence-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 14:28:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "solanovisitor",
"github_project": "hacs-ai",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hacs-persistence"
}
JSON
