# HACS – Healthcare Agent Communication Standard
[](https://github.com/solanovisitor/hacs)
[](https://python.org)
[](https://github.com/solanovisitor/hacs/actions)
[](LICENSE)
HACS provides standardized data models and tools for healthcare AI applications, with full FHIR compatibility and optimized interfaces for LLM integration.
## Installation
```bash
pip install healthcare-hacs
```
For development:
```bash
git clone https://github.com/solanovisitor/hacs.git
cd hacs && uv sync
```
## Quick Start
### Basic Usage
```python
from hacs_models import Patient, Observation
from hacs_core import Actor
# Create healthcare provider
doctor = Actor(name="Dr. Smith", role="physician")
# Create patient
patient = Patient(full_name="John Doe", age=45, gender="male")
# Record observation
bp = Observation(
subject=patient.id,
code_text="blood pressure",
value_numeric=120,
unit="mmHg"
)
print(f"Patient: {patient.display_name}")
print(f"Observation: {bp.display_name} = {bp.get_numeric_value()} {bp.get_unit()}")
```
### FHIR-Compatible Usage
```python
from hacs_models import Patient, Observation
from datetime import date
# Create patient with FHIR fields
patient = Patient(
given=["John"],
family="Doe",
gender="male",
birth_date=date(1979, 1, 1)
)
# Create observation with LOINC code
bp = Observation(
status="final",
code={
"coding": [{
"system": "http://loinc.org",
"code": "8480-6",
"display": "Systolic blood pressure"
}]
},
subject=patient.id,
value_quantity={"value": 120, "unit": "mmHg"}
)
```
## Core Features
### Data Models
- **Patient**: Demographics, identifiers, contact information
- **Observation**: Clinical measurements with LOINC codes
- **Encounter**: Healthcare visits and interactions
- **Actor**: Healthcare providers with role-based permissions
- **Evidence**: Clinical evidence with confidence scoring
- **MemoryBlock**: Structured memory for AI agents
### Tools
- **CRUD Operations**: Create, read, update, delete resources
- **FHIR Conversion**: Bidirectional FHIR R4/R5 conversion
- **Validation**: Resource validation and error checking
- **Vector Support**: Metadata for vector databases
- **CLI Interface**: Command-line operations
### AI Integration
- **LangGraph**: Workflow adapter for clinical decision support
- **CrewAI**: Multi-agent healthcare workflows
- **Vector Stores**: Pinecone and Qdrant integration
- **Memory Management**: Episodic, procedural, and executive memory
## Documentation
| Guide | Description |
|-------|-------------|
| [Installation](docs/getting-started/installation.md) | Setup and dependencies |
| [Quick Start](docs/getting-started/quickstart.md) | 5-minute tutorial |
| [Core Concepts](docs/getting-started/concepts.md) | Understanding HACS |
| [Architecture](docs/getting-started/architecture.md) | System design |
| [Basic Usage](docs/examples/basic-usage.md) | Code examples |
| [API Reference](docs/reference/api.md) | Complete API documentation |
## Examples
### Simple Patient Workflow
```python
from hacs_models import Patient, Observation
from hacs_core import Actor, MemoryBlock
# Setup
doctor = Actor(name="Dr. Johnson", role="physician")
patient = Patient(full_name="Maria Rodriguez", age=32, gender="female")
# Clinical data
vitals = [
Observation(subject=patient.id, code_text="blood pressure", value_numeric=118, unit="mmHg"),
Observation(subject=patient.id, code_text="heart rate", value_numeric=72, unit="bpm"),
Observation(subject=patient.id, code_text="temperature", value_numeric=98.6, unit="F")
]
# Store clinical memory
memory = MemoryBlock(
content="Patient has normal vital signs",
memory_type="episodic",
importance_score=0.7
)
```
### Vector Database Integration
```python
from hacs_tools.vectorization import VectorMetadata
metadata = VectorMetadata(
resource_type="Patient",
resource_id=patient.id,
content_hash="abc123",
metadata={"name": patient.display_name, "age": patient.age_years}
)
```
### FHIR Conversion
```python
from hacs_fhir import to_fhir, from_fhir
# Convert to FHIR
fhir_patient = to_fhir(patient)
# Convert back
hacs_patient = from_fhir(fhir_patient)
```
## Testing
```bash
# Quick verification
uv run python tests/test_quick_start.py
# Full test suite
uv run pytest tests/ -v
# LLM-friendly features
uv run python tests/test_llm_friendly.py
```
## Packages
| Package | Purpose | Status |
|---------|---------|--------|
| `hacs-core` | Base models, Actor, Memory, Evidence | Stable |
| `hacs-models` | Patient, Observation, Encounter, AgentMessage | Stable |
| `hacs-tools` | CRUD operations, adapters, validation | Stable |
| `hacs-fhir` | FHIR R4/R5 conversion | Stable |
| `hacs-api` | FastAPI service | Basic |
| `hacs-cli` | Command-line interface | Stable |
| `hacs-qdrant` | Qdrant vector store | Stable |
| `hacs-openai` | OpenAI embeddings | Stable |
| `hacs-pinecone` | Pinecone vector store | Stable |
## Requirements
- Python 3.10+
- Pydantic 2.0+
- Optional: Vector database (Pinecone, Qdrant)
- Optional: LLM providers (OpenAI, Anthropic)
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Run `uv run pytest tests/`
5. Submit a pull request
See [Contributing Guidelines](docs/contributing/guidelines.md) for details.
## License
Apache 2.0 - see [LICENSE](LICENSE) for details.
## Support
- [Documentation](docs/README.md)
- [GitHub Issues](https://github.com/solanovisitor/hacs/issues)
- [GitHub Discussions](https://github.com/solanovisitor/hacs/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "healthcare-hacs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Solano Todeschini <solano.todeschini@gmail.com>",
"keywords": "agents, ai, clinical, communication, fhir, healthcare, interoperability, standard",
"author": null,
"author_email": "Solano Todeschini <solano.todeschini@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a6/d7/1b9e8cca457630be514a89f16ad6e05e7dc06fd7fe84059bff2678f57018/healthcare_hacs-0.2.1.tar.gz",
"platform": null,
"description": "# HACS \u2013 Healthcare Agent Communication Standard\n\n[](https://github.com/solanovisitor/hacs)\n[](https://python.org)\n[](https://github.com/solanovisitor/hacs/actions)\n[](LICENSE)\n\nHACS provides standardized data models and tools for healthcare AI applications, with full FHIR compatibility and optimized interfaces for LLM integration.\n\n## Installation\n\n```bash\npip install healthcare-hacs\n```\n\nFor development:\n```bash\ngit clone https://github.com/solanovisitor/hacs.git\ncd hacs && uv sync\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom hacs_models import Patient, Observation\nfrom hacs_core import Actor\n\n# Create healthcare provider\ndoctor = Actor(name=\"Dr. Smith\", role=\"physician\")\n\n# Create patient\npatient = Patient(full_name=\"John Doe\", age=45, gender=\"male\")\n\n# Record observation\nbp = Observation(\n subject=patient.id,\n code_text=\"blood pressure\",\n value_numeric=120,\n unit=\"mmHg\"\n)\n\nprint(f\"Patient: {patient.display_name}\")\nprint(f\"Observation: {bp.display_name} = {bp.get_numeric_value()} {bp.get_unit()}\")\n```\n\n### FHIR-Compatible Usage\n\n```python\nfrom hacs_models import Patient, Observation\nfrom datetime import date\n\n# Create patient with FHIR fields\npatient = Patient(\n given=[\"John\"],\n family=\"Doe\",\n gender=\"male\",\n birth_date=date(1979, 1, 1)\n)\n\n# Create observation with LOINC code\nbp = Observation(\n status=\"final\",\n code={\n \"coding\": [{\n \"system\": \"http://loinc.org\",\n \"code\": \"8480-6\",\n \"display\": \"Systolic blood pressure\"\n }]\n },\n subject=patient.id,\n value_quantity={\"value\": 120, \"unit\": \"mmHg\"}\n)\n```\n\n## Core Features\n\n### Data Models\n- **Patient**: Demographics, identifiers, contact information\n- **Observation**: Clinical measurements with LOINC codes\n- **Encounter**: Healthcare visits and interactions\n- **Actor**: Healthcare providers with role-based permissions\n- **Evidence**: Clinical evidence with confidence scoring\n- **MemoryBlock**: Structured memory for AI agents\n\n### Tools\n- **CRUD Operations**: Create, read, update, delete resources\n- **FHIR Conversion**: Bidirectional FHIR R4/R5 conversion\n- **Validation**: Resource validation and error checking\n- **Vector Support**: Metadata for vector databases\n- **CLI Interface**: Command-line operations\n\n### AI Integration\n- **LangGraph**: Workflow adapter for clinical decision support\n- **CrewAI**: Multi-agent healthcare workflows\n- **Vector Stores**: Pinecone and Qdrant integration\n- **Memory Management**: Episodic, procedural, and executive memory\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Installation](docs/getting-started/installation.md) | Setup and dependencies |\n| [Quick Start](docs/getting-started/quickstart.md) | 5-minute tutorial |\n| [Core Concepts](docs/getting-started/concepts.md) | Understanding HACS |\n| [Architecture](docs/getting-started/architecture.md) | System design |\n| [Basic Usage](docs/examples/basic-usage.md) | Code examples |\n| [API Reference](docs/reference/api.md) | Complete API documentation |\n\n## Examples\n\n### Simple Patient Workflow\n```python\nfrom hacs_models import Patient, Observation\nfrom hacs_core import Actor, MemoryBlock\n\n# Setup\ndoctor = Actor(name=\"Dr. Johnson\", role=\"physician\")\npatient = Patient(full_name=\"Maria Rodriguez\", age=32, gender=\"female\")\n\n# Clinical data\nvitals = [\n Observation(subject=patient.id, code_text=\"blood pressure\", value_numeric=118, unit=\"mmHg\"),\n Observation(subject=patient.id, code_text=\"heart rate\", value_numeric=72, unit=\"bpm\"),\n Observation(subject=patient.id, code_text=\"temperature\", value_numeric=98.6, unit=\"F\")\n]\n\n# Store clinical memory\nmemory = MemoryBlock(\n content=\"Patient has normal vital signs\",\n memory_type=\"episodic\",\n importance_score=0.7\n)\n```\n\n### Vector Database Integration\n```python\nfrom hacs_tools.vectorization import VectorMetadata\n\nmetadata = VectorMetadata(\n resource_type=\"Patient\",\n resource_id=patient.id,\n content_hash=\"abc123\",\n metadata={\"name\": patient.display_name, \"age\": patient.age_years}\n)\n```\n\n### FHIR Conversion\n```python\nfrom hacs_fhir import to_fhir, from_fhir\n\n# Convert to FHIR\nfhir_patient = to_fhir(patient)\n\n# Convert back\nhacs_patient = from_fhir(fhir_patient)\n```\n\n## Testing\n\n```bash\n# Quick verification\nuv run python tests/test_quick_start.py\n\n# Full test suite\nuv run pytest tests/ -v\n\n# LLM-friendly features\nuv run python tests/test_llm_friendly.py\n```\n\n## Packages\n\n| Package | Purpose | Status |\n|---------|---------|--------|\n| `hacs-core` | Base models, Actor, Memory, Evidence | Stable |\n| `hacs-models` | Patient, Observation, Encounter, AgentMessage | Stable |\n| `hacs-tools` | CRUD operations, adapters, validation | Stable |\n| `hacs-fhir` | FHIR R4/R5 conversion | Stable |\n| `hacs-api` | FastAPI service | Basic |\n| `hacs-cli` | Command-line interface | Stable |\n| `hacs-qdrant` | Qdrant vector store | Stable |\n| `hacs-openai` | OpenAI embeddings | Stable |\n| `hacs-pinecone` | Pinecone vector store | Stable |\n\n## Requirements\n\n- Python 3.10+\n- Pydantic 2.0+\n- Optional: Vector database (Pinecone, Qdrant)\n- Optional: LLM providers (OpenAI, Anthropic)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Run `uv run pytest tests/`\n5. Submit a pull request\n\nSee [Contributing Guidelines](docs/contributing/guidelines.md) for details.\n\n## License\n\nApache 2.0 - see [LICENSE](LICENSE) for details.\n\n## Support\n\n- [Documentation](docs/README.md)\n- [GitHub Issues](https://github.com/solanovisitor/hacs/issues)\n- [GitHub Discussions](https://github.com/solanovisitor/hacs/discussions)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Healthcare Agent Communication Standard - Production-ready multi-package workspace",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/solanovisitor/hacs/issues",
"Changelog": "https://github.com/solanovisitor/hacs/blob/main/docs/reference/changelog.md",
"Documentation": "https://github.com/solanovisitor/hacs/blob/main/docs/README.md",
"Homepage": "https://github.com/solanovisitor/hacs",
"Repository": "https://github.com/solanovisitor/hacs"
},
"split_keywords": [
"agents",
" ai",
" clinical",
" communication",
" fhir",
" healthcare",
" interoperability",
" standard"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2943c846b21616054bb1d756828f69fb54ad19f7aac684531ba1072a0fdd74d6",
"md5": "adb54fac203f7bc03f85a4ba10017efd",
"sha256": "3ebb31bc1ea46c1e00705ca4b7c350ab6274c304e0f276d05c69364664914d5a"
},
"downloads": -1,
"filename": "healthcare_hacs-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "adb54fac203f7bc03f85a4ba10017efd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15537,
"upload_time": "2025-07-08T20:28:39",
"upload_time_iso_8601": "2025-07-08T20:28:39.692060Z",
"url": "https://files.pythonhosted.org/packages/29/43/c846b21616054bb1d756828f69fb54ad19f7aac684531ba1072a0fdd74d6/healthcare_hacs-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a6d71b9e8cca457630be514a89f16ad6e05e7dc06fd7fe84059bff2678f57018",
"md5": "c924649b94077e5662985ac341448ba0",
"sha256": "7ea14041fbdf488402898ab85339dc58e2251015e77d400c24cd7746b7f9f4d0"
},
"downloads": -1,
"filename": "healthcare_hacs-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "c924649b94077e5662985ac341448ba0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 710760,
"upload_time": "2025-07-08T20:28:41",
"upload_time_iso_8601": "2025-07-08T20:28:41.397863Z",
"url": "https://files.pythonhosted.org/packages/a6/d7/1b9e8cca457630be514a89f16ad6e05e7dc06fd7fe84059bff2678f57018/healthcare_hacs-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 20:28:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "solanovisitor",
"github_project": "hacs",
"github_not_found": true,
"lcname": "healthcare-hacs"
}
JSON
