# HACS OpenAI Integration
Generic OpenAI integration for HACS providing embeddings, structured outputs, tool calling, and configurable clients that work with any HACS types.
## Features
- **Embeddings**: OpenAI embedding models for vectorization
- **Structured Outputs**: Generate any HACS model using instructor or native structured outputs
- **Tool Calling**: Both legacy function calling and new tool calling formats
- **Configurable Clients**: Fully configurable OpenAI clients with custom parameters
- **Generic Utilities**: Work with any HACS Pydantic models
- **Batch Processing**: Efficient batch operations for high-volume use cases
## Installation
```bash
pip install hacs-openai
```
## Quick Start
### Basic Client Setup
```python
from hacs_openai import create_openai_client
# Basic client with defaults
client = create_openai_client()
# Custom configuration
client = create_openai_client(
model="gpt-4o",
api_key="your-api-key",
base_url="https://api.openai.com/v1", # Custom API URL
temperature=0.7,
max_tokens=4096
)
```
### Structured Output Generation
```python
from hacs_openai import create_structured_generator
from hacs_models import Patient
# Create generator
generator = create_structured_generator(
model="gpt-4o",
temperature=0.3, # Lower for structured output
api_key="your-api-key"
)
# Generate any HACS model
patient = generator.generate_hacs_resource(
resource_type=Patient,
user_prompt="Create a patient record for John Doe, 30 years old, male"
)
print(f"Generated: {patient.display_name}")
```
### Tool Calling
```python
from hacs_openai import OpenAIClient, OpenAIToolRegistry
# Setup client and tool registry
client = OpenAIClient()
registry = OpenAIToolRegistry()
# Register any function as a tool
def calculate_value(input_data: str, multiplier: int = 1) -> str:
return f"Result: {input_data} * {multiplier}"
registry.register_tool(
name="calculate_value",
function=calculate_value,
description="Calculate a value with multiplier",
parameters={
"type": "object",
"properties": {
"input_data": {"type": "string"},
"multiplier": {"type": "integer", "default": 1}
},
"required": ["input_data"]
}
)
# Use tools in conversation
response = client.tool_call(
messages=[
{"role": "user", "content": "Calculate value for 'test' with multiplier 5"}
],
tools=registry.get_tools()
)
```
### Embeddings for Vector Search
```python
from hacs_openai import create_openai_embedding
# Create embedding model
embedding_model = create_openai_embedding(
model="text-embedding-3-small",
api_key="your-api-key"
)
# Generate embeddings
text = "Any text content"
embedding = embedding_model.embed(text)
print(f"Embedding dimensions: {len(embedding)}")
```
## Advanced Usage
### Custom System Prompts
```python
from hacs_openai import OpenAIStructuredGenerator
# Custom system prompt
system_prompt = """You are an AI assistant that generates structured data.
Follow the provided schema exactly and ensure all required fields are populated."""
generator = OpenAIStructuredGenerator(
model="gpt-4o",
temperature=0.3,
system_prompt=system_prompt
)
# Generate with custom prompt
result = generator.generate_hacs_resource(
resource_type=YourModel,
user_prompt="Generate data based on this input"
)
```
### Batch Processing
```python
from hacs_openai import create_structured_generator
generator = create_structured_generator()
# Generate multiple resources
prompts = [
"Generate first resource",
"Generate second resource",
"Generate third resource"
]
results = generator.generate_batch_resources(
resource_type=YourModel,
prompts=prompts
)
for result in results:
if result:
print(f"Generated: {result}")
```
### Native Structured Outputs
```python
from hacs_openai import OpenAIClient
client = OpenAIClient()
# Use OpenAI's native structured output
response = client.native_structured_output(
messages=[
{"role": "user", "content": "Generate structured data"}
],
response_schema=YourModel.model_json_schema()
)
# Parse response
result = YourModel(**response)
```
## Configuration
### Environment Variables
```bash
# OpenAI API configuration
export OPENAI_API_KEY="your-api-key"
export OPENAI_API_URL="https://api.openai.com/v1" # Custom API URL
export OPENAI_ORGANIZATION="your-org-id"
# Default model settings
export OPENAI_DEFAULT_MODEL="gpt-4o"
export OPENAI_DEFAULT_TEMPERATURE="0.7"
```
### Client Configuration
```python
from hacs_openai import OpenAIClient
# Fully configured client
client = OpenAIClient(
model="gpt-4o",
api_key="your-api-key",
base_url="https://api.openai.com/v1",
organization="your-org-id",
timeout=30.0,
max_retries=3,
temperature=0.7,
max_tokens=4096,
top_p=1.0,
frequency_penalty=0.0,
presence_penalty=0.0
)
```
## Error Handling
```python
from hacs_openai import create_structured_generator
import openai
generator = create_structured_generator()
try:
result = generator.generate_hacs_resource(
resource_type=YourModel,
user_prompt="Generate data"
)
except openai.APIError as e:
print(f"OpenAI API error: {e}")
except ValueError as e:
print(f"Validation error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
```
## Performance Optimization
### Batch Operations
```python
# Process multiple requests efficiently
results = generator.generate_batch_resources(
resource_type=YourModel,
prompts=batch_prompts,
max_tokens=1000, # Limit tokens per request
temperature=0.1 # Lower temperature for consistency
)
```
### Caching
```python
from functools import lru_cache
@lru_cache(maxsize=100)
def cached_generate(prompt: str) -> YourModel:
return generator.generate_hacs_resource(
resource_type=YourModel,
user_prompt=prompt
)
```
## Generic Features
### Work with Any HACS Model
The utilities work with any Pydantic model:
```python
from pydantic import BaseModel
from hacs_openai import create_structured_generator
class CustomModel(BaseModel):
name: str
value: int
description: str
generator = create_structured_generator()
result = generator.generate_hacs_resource(
resource_type=CustomModel,
user_prompt="Generate a custom model instance"
)
```
### Tool Integration
```python
# Register tools that work with any data
def process_data(data: dict, operation: str) -> dict:
# Generic data processing
return {"processed": data, "operation": operation}
registry = OpenAIToolRegistry()
registry.register_tool(
name="process_data",
function=process_data,
description="Process any data with specified operation",
parameters={
"type": "object",
"properties": {
"data": {"type": "object"},
"operation": {"type": "string"}
},
"required": ["data", "operation"]
}
)
```
## API Reference
### Classes
- `OpenAIClient`: Enhanced OpenAI client with HACS integration
- `OpenAIStructuredGenerator`: Generate any HACS model from text
- `OpenAIToolRegistry`: Registry for tools and functions
- `OpenAIEmbedding`: Embedding model for vectorization
### Functions
- `create_openai_client()`: Create configured OpenAI client
- `create_structured_generator()`: Create structured output generator
- `create_openai_embedding()`: Create embedding model
- `create_openai_vectorizer()`: Create complete vectorizer
## Contributing
See [Contributing Guidelines](../../CONTRIBUTING.md) for development setup and contribution process.
## License
Apache License 2.0 - see [LICENSE](../../LICENSE) for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "hacs-openai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agents, ai, clinical, communication, embeddings, fhir, function-calling, gpt, healthcare, language-model, llm, openai, semantic-search, standard, structured-output, tool-calling, vectorization",
"author": null,
"author_email": "Solano Todeschini <solano.todeschini@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/51/ca/98ad33715e20d781b9a25c5f81691bf45560014adc09810c1038212ea7e4/hacs_openai-0.2.3.tar.gz",
"platform": null,
"description": "# HACS OpenAI Integration\n\nGeneric OpenAI integration for HACS providing embeddings, structured outputs, tool calling, and configurable clients that work with any HACS types.\n\n## Features\n\n- **Embeddings**: OpenAI embedding models for vectorization\n- **Structured Outputs**: Generate any HACS model using instructor or native structured outputs\n- **Tool Calling**: Both legacy function calling and new tool calling formats\n- **Configurable Clients**: Fully configurable OpenAI clients with custom parameters\n- **Generic Utilities**: Work with any HACS Pydantic models\n- **Batch Processing**: Efficient batch operations for high-volume use cases\n\n## Installation\n\n```bash\npip install hacs-openai\n```\n\n## Quick Start\n\n### Basic Client Setup\n\n```python\nfrom hacs_openai import create_openai_client\n\n# Basic client with defaults\nclient = create_openai_client()\n\n# Custom configuration\nclient = create_openai_client(\n model=\"gpt-4o\",\n api_key=\"your-api-key\",\n base_url=\"https://api.openai.com/v1\", # Custom API URL\n temperature=0.7,\n max_tokens=4096\n)\n```\n\n### Structured Output Generation\n\n```python\nfrom hacs_openai import create_structured_generator\nfrom hacs_models import Patient\n\n# Create generator\ngenerator = create_structured_generator(\n model=\"gpt-4o\",\n temperature=0.3, # Lower for structured output\n api_key=\"your-api-key\"\n)\n\n# Generate any HACS model\npatient = generator.generate_hacs_resource(\n resource_type=Patient,\n user_prompt=\"Create a patient record for John Doe, 30 years old, male\"\n)\n\nprint(f\"Generated: {patient.display_name}\")\n```\n\n### Tool Calling\n\n```python\nfrom hacs_openai import OpenAIClient, OpenAIToolRegistry\n\n# Setup client and tool registry\nclient = OpenAIClient()\nregistry = OpenAIToolRegistry()\n\n# Register any function as a tool\ndef calculate_value(input_data: str, multiplier: int = 1) -> str:\n return f\"Result: {input_data} * {multiplier}\"\n\nregistry.register_tool(\n name=\"calculate_value\",\n function=calculate_value,\n description=\"Calculate a value with multiplier\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"input_data\": {\"type\": \"string\"},\n \"multiplier\": {\"type\": \"integer\", \"default\": 1}\n },\n \"required\": [\"input_data\"]\n }\n)\n\n# Use tools in conversation\nresponse = client.tool_call(\n messages=[\n {\"role\": \"user\", \"content\": \"Calculate value for 'test' with multiplier 5\"}\n ],\n tools=registry.get_tools()\n)\n```\n\n### Embeddings for Vector Search\n\n```python\nfrom hacs_openai import create_openai_embedding\n\n# Create embedding model\nembedding_model = create_openai_embedding(\n model=\"text-embedding-3-small\",\n api_key=\"your-api-key\"\n)\n\n# Generate embeddings\ntext = \"Any text content\"\nembedding = embedding_model.embed(text)\nprint(f\"Embedding dimensions: {len(embedding)}\")\n```\n\n## Advanced Usage\n\n### Custom System Prompts\n\n```python\nfrom hacs_openai import OpenAIStructuredGenerator\n\n# Custom system prompt\nsystem_prompt = \"\"\"You are an AI assistant that generates structured data.\nFollow the provided schema exactly and ensure all required fields are populated.\"\"\"\n\ngenerator = OpenAIStructuredGenerator(\n model=\"gpt-4o\",\n temperature=0.3,\n system_prompt=system_prompt\n)\n\n# Generate with custom prompt\nresult = generator.generate_hacs_resource(\n resource_type=YourModel,\n user_prompt=\"Generate data based on this input\"\n)\n```\n\n### Batch Processing\n\n```python\nfrom hacs_openai import create_structured_generator\n\ngenerator = create_structured_generator()\n\n# Generate multiple resources\nprompts = [\n \"Generate first resource\",\n \"Generate second resource\", \n \"Generate third resource\"\n]\n\nresults = generator.generate_batch_resources(\n resource_type=YourModel,\n prompts=prompts\n)\n\nfor result in results:\n if result:\n print(f\"Generated: {result}\")\n```\n\n### Native Structured Outputs\n\n```python\nfrom hacs_openai import OpenAIClient\n\nclient = OpenAIClient()\n\n# Use OpenAI's native structured output\nresponse = client.native_structured_output(\n messages=[\n {\"role\": \"user\", \"content\": \"Generate structured data\"}\n ],\n response_schema=YourModel.model_json_schema()\n)\n\n# Parse response\nresult = YourModel(**response)\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# OpenAI API configuration\nexport OPENAI_API_KEY=\"your-api-key\"\nexport OPENAI_API_URL=\"https://api.openai.com/v1\" # Custom API URL\nexport OPENAI_ORGANIZATION=\"your-org-id\"\n\n# Default model settings\nexport OPENAI_DEFAULT_MODEL=\"gpt-4o\"\nexport OPENAI_DEFAULT_TEMPERATURE=\"0.7\"\n```\n\n### Client Configuration\n\n```python\nfrom hacs_openai import OpenAIClient\n\n# Fully configured client\nclient = OpenAIClient(\n model=\"gpt-4o\",\n api_key=\"your-api-key\",\n base_url=\"https://api.openai.com/v1\",\n organization=\"your-org-id\",\n timeout=30.0,\n max_retries=3,\n temperature=0.7,\n max_tokens=4096,\n top_p=1.0,\n frequency_penalty=0.0,\n presence_penalty=0.0\n)\n```\n\n## Error Handling\n\n```python\nfrom hacs_openai import create_structured_generator\nimport openai\n\ngenerator = create_structured_generator()\n\ntry:\n result = generator.generate_hacs_resource(\n resource_type=YourModel,\n user_prompt=\"Generate data\"\n )\nexcept openai.APIError as e:\n print(f\"OpenAI API error: {e}\")\nexcept ValueError as e:\n print(f\"Validation error: {e}\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n## Performance Optimization\n\n### Batch Operations\n\n```python\n# Process multiple requests efficiently\nresults = generator.generate_batch_resources(\n resource_type=YourModel,\n prompts=batch_prompts,\n max_tokens=1000, # Limit tokens per request\n temperature=0.1 # Lower temperature for consistency\n)\n```\n\n### Caching\n\n```python\nfrom functools import lru_cache\n\n@lru_cache(maxsize=100)\ndef cached_generate(prompt: str) -> YourModel:\n return generator.generate_hacs_resource(\n resource_type=YourModel,\n user_prompt=prompt\n )\n```\n\n## Generic Features\n\n### Work with Any HACS Model\n\nThe utilities work with any Pydantic model:\n\n```python\nfrom pydantic import BaseModel\nfrom hacs_openai import create_structured_generator\n\nclass CustomModel(BaseModel):\n name: str\n value: int\n description: str\n\ngenerator = create_structured_generator()\nresult = generator.generate_hacs_resource(\n resource_type=CustomModel,\n user_prompt=\"Generate a custom model instance\"\n)\n```\n\n### Tool Integration\n\n```python\n# Register tools that work with any data\ndef process_data(data: dict, operation: str) -> dict:\n # Generic data processing\n return {\"processed\": data, \"operation\": operation}\n\nregistry = OpenAIToolRegistry()\nregistry.register_tool(\n name=\"process_data\",\n function=process_data,\n description=\"Process any data with specified operation\",\n parameters={\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\"type\": \"object\"},\n \"operation\": {\"type\": \"string\"}\n },\n \"required\": [\"data\", \"operation\"]\n }\n)\n```\n\n## API Reference\n\n### Classes\n\n- `OpenAIClient`: Enhanced OpenAI client with HACS integration\n- `OpenAIStructuredGenerator`: Generate any HACS model from text\n- `OpenAIToolRegistry`: Registry for tools and functions\n- `OpenAIEmbedding`: Embedding model for vectorization\n\n### Functions\n\n- `create_openai_client()`: Create configured OpenAI client\n- `create_structured_generator()`: Create structured output generator\n- `create_openai_embedding()`: Create embedding model\n- `create_openai_vectorizer()`: Create complete vectorizer\n\n## Contributing\n\nSee [Contributing Guidelines](../../CONTRIBUTING.md) for development setup and contribution process.\n\n## License\n\nApache License 2.0 - see [LICENSE](../../LICENSE) for details. ",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "OpenAI integration for HACS (Healthcare Agent Communication Standard)",
"version": "0.2.3",
"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/tree/main/docs",
"Homepage": "https://github.com/solanovisitor/hacs",
"Repository": "https://github.com/solanovisitor/hacs"
},
"split_keywords": [
"agents",
" ai",
" clinical",
" communication",
" embeddings",
" fhir",
" function-calling",
" gpt",
" healthcare",
" language-model",
" llm",
" openai",
" semantic-search",
" standard",
" structured-output",
" tool-calling",
" vectorization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "07408bdad5ba5685539e363c1620c6d9f5d655dc34460f042eae3d7d0482a185",
"md5": "fff1ed5527a5c40b6c7438f134e0c3c6",
"sha256": "872f6a120a86206dcc7a90e7236c81c6799f87a7a058999da2769f97c06cf345"
},
"downloads": -1,
"filename": "hacs_openai-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fff1ed5527a5c40b6c7438f134e0c3c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6747,
"upload_time": "2025-07-09T16:24:48",
"upload_time_iso_8601": "2025-07-09T16:24:48.375745Z",
"url": "https://files.pythonhosted.org/packages/07/40/8bdad5ba5685539e363c1620c6d9f5d655dc34460f042eae3d7d0482a185/hacs_openai-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "51ca98ad33715e20d781b9a25c5f81691bf45560014adc09810c1038212ea7e4",
"md5": "e918523e2743fc2ff879117586b6c275",
"sha256": "f344c3105b3de2859f93b9dc7c4a35d95705afd8863266216f31bf824b82776d"
},
"downloads": -1,
"filename": "hacs_openai-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "e918523e2743fc2ff879117586b6c275",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 8664,
"upload_time": "2025-07-09T16:24:49",
"upload_time_iso_8601": "2025-07-09T16:24:49.304523Z",
"url": "https://files.pythonhosted.org/packages/51/ca/98ad33715e20d781b9a25c5f81691bf45560014adc09810c1038212ea7e4/hacs_openai-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 16:24:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "solanovisitor",
"github_project": "hacs",
"github_not_found": true,
"lcname": "hacs-openai"
}
JSON
