hacs-openai


Namehacs-openai JSON
Version 0.2.3 PyPI version JSON
download
home_pageNone
SummaryOpenAI integration for HACS (Healthcare Agent Communication Standard)
upload_time2025-07-09 16:24:49
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseApache-2.0
keywords agents ai clinical communication embeddings fhir function-calling gpt healthcare language-model llm openai semantic-search standard structured-output tool-calling vectorization
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 1.46137s