openai-sdk-helpers 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

openai_sdk_helpers/agent/summarizer.py

@@ -3,13 +3,12 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, Optional, Type
+from typing import Any, Dict, Optional
 
 from ..structure import SummaryStructure
 from ..structure.base import StructureBase
 from .base import AgentBase
-from .config import AgentConfiguration
-from .prompt_utils import DEFAULT_PROMPT_DIR
+from .configuration import AgentConfiguration
 
 
 class SummarizerAgent(AgentBase):
@@ -21,11 +20,10 @@ class SummarizerAgent(AgentBase):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Optional directory containing Jinja prompt templates. Defaults to the
-        packaged ``prompt`` directory when not provided.
-    default_model : str or None, default=None
-        Fallback model identifier when not specified elsewhere.
+    template_path : Path | str | None, default=None
+        Optional template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use for summarization.
     output_structure : type[StructureBase], default=SummaryStructure
         Type describing the expected summary output.
 
@@ -34,7 +32,7 @@ class SummarizerAgent(AgentBase):
     Basic usage with default settings:
 
     >>> from openai_sdk_helpers.agent import SummarizerAgent
-    >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+    >>> summarizer = SummarizerAgent(model="gpt-4o-mini")
     >>> summary = summarizer.run_sync("Long text to summarize...")
     >>> print(summary.text)
 
@@ -42,7 +40,7 @@ class SummarizerAgent(AgentBase):
 
     >>> import asyncio
     >>> async def main():
-    ...     summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+    ...     summarizer = SummarizerAgent(model="gpt-4o-mini")
     ...     result = await summarizer.run_agent(
     ...         text="Article content...",
     ...         metadata={"source": "news.txt", "date": "2025-01-01"}
@@ -59,42 +57,38 @@ class SummarizerAgent(AgentBase):
     def __init__(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
-        output_structure: Type[StructureBase] = SummaryStructure,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
         """Initialize the summarizer agent configuration.
 
         Parameters
         ----------
-        prompt_dir : Path or None, default=None
-            Optional directory containing Jinja prompt templates. Defaults to the
-            packaged ``prompt`` directory when not provided.
-        default_model : str or None, default=None
-            Fallback model identifier when not specified elsewhere.
-        output_structure : type[StructureBase], default=SummaryStructure
-            Type describing the expected summary output.
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use for summarization.
 
         Raises
         ------
         ValueError
-            If the default model is not provided.
+            If the model is not provided.
 
         Examples
         --------
-        >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+        >>> summarizer = SummarizerAgent(model="gpt-4o-mini")
         """
-        config = AgentConfiguration(
+        configuration = AgentConfiguration(
             name="summarizer",
             instructions="Agent instructions",
             description="Summarize passages into concise findings.",
-            output_structure=output_structure,
-        )
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(
-            config=config, prompt_dir=prompt_directory, default_model=default_model
+            template_path=template_path,
+            output_structure=SummaryStructure,
+            model=model,
         )
 
+        super().__init__(configuration=configuration)
+
     async def run_agent(
         self, text: str, metadata: Optional[Dict[str, Any]] = None
     ) -> Any:

openai_sdk_helpers/agent/translator.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from .base import AgentBase
-from .config import AgentConfiguration
-from .prompt_utils import DEFAULT_PROMPT_DIR
+
 from ..structure import TranslationStructure
 from ..structure.base import StructureBase
 
+from .base import AgentBase
+from .configuration import AgentConfiguration
+
 
 class TranslatorAgent(AgentBase):
     """Translate text into a target language.
@@ -20,18 +21,17 @@ class TranslatorAgent(AgentBase):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Optional directory containing Jinja prompt templates. Defaults to the
-        packaged ``prompt`` directory when not provided.
-    default_model : str or None, default=None
-        Fallback model identifier when not specified elsewhere.
+    template_path : Path | str | None, default=None
+        Optional template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use for translation.
 
     Examples
     --------
     Basic translation:
 
     >>> from openai_sdk_helpers.agent import TranslatorAgent
-    >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
+    >>> translator = TranslatorAgent(model="gpt-4o-mini")
     >>> result = translator.run_sync("Hello world", target_language="Spanish")
     >>> print(result.text)
     'Hola mundo'
@@ -40,7 +40,7 @@ class TranslatorAgent(AgentBase):
 
     >>> import asyncio
     >>> async def main():
-    ...     translator = TranslatorAgent(default_model="gpt-4o-mini")
+    ...     translator = TranslatorAgent(model="gpt-4o-mini")
     ...     result = await translator.run_agent(
     ...         text="Good morning",
     ...         target_language="French",
@@ -60,38 +60,36 @@ class TranslatorAgent(AgentBase):
     def __init__(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
         """Initialize the translation agent configuration.
 
         Parameters
         ----------
-        prompt_dir : Path or None, default=None
-            Optional directory containing Jinja prompt templates. Defaults to the
-            packaged ``prompt`` directory when not provided.
-        default_model : str or None, default=None
-            Fallback model identifier when not specified elsewhere.
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use for translation.
 
         Raises
         ------
         ValueError
-            If the default model is not provided.
+            If the model is not provided.
 
         Examples
         --------
-        >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
+        >>> translator = TranslatorAgent(model="gpt-4o-mini")
         """
-        config = AgentConfiguration(
+        configuration = AgentConfiguration(
             name="translator",
             instructions="Agent instructions",
             description="Translate text into the requested language.",
+            template_path=template_path,
             output_structure=TranslationStructure,
+            model=model,
         )
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(
-            config=config, prompt_dir=prompt_directory, default_model=default_model
-        )
+        super().__init__(configuration=configuration)
 
     async def run_agent(
         self,

openai_sdk_helpers/agent/{validation.py → validator.py}

@@ -7,8 +7,7 @@ from typing import Any, Dict, Optional
 
 from ..structure.validation import ValidationResultStructure
 from .base import AgentBase
-from .config import AgentConfiguration
-from .prompt_utils import DEFAULT_PROMPT_DIR
+from .configuration import AgentConfiguration
 
 
 class ValidatorAgent(AgentBase):
@@ -20,18 +19,17 @@ class ValidatorAgent(AgentBase):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Optional directory containing Jinja prompt templates. Defaults to the
-        packaged ``prompt`` directory when not provided.
-    default_model : str or None, default=None
-        Fallback model identifier when not specified elsewhere.
+    template_path : Path | str | None, default=None
+        Optional template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use for validation.
 
     Examples
     --------
     Validate user input:
 
     >>> from openai_sdk_helpers.agent import ValidatorAgent
-    >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
+    >>> validator = ValidatorAgent(model="gpt-4o-mini")
     >>> result = validator.run_sync("Tell me about Python programming")
     >>> print(result.input_safe)  # True
     >>> print(result.violations)  # []
@@ -40,7 +38,7 @@ class ValidatorAgent(AgentBase):
 
     >>> import asyncio
     >>> async def main():
-    ...     validator = ValidatorAgent(default_model="gpt-4o-mini")
+    ...     validator = ValidatorAgent(model="gpt-4o-mini")
     ...     result = await validator.run_agent(
     ...         user_input="Summarize this document",
     ...         agent_output="Summary containing PII...",
@@ -59,38 +57,36 @@ class ValidatorAgent(AgentBase):
     def __init__(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
         """Initialize the validator agent configuration.
 
         Parameters
         ----------
-        prompt_dir : Path or None, default=None
-            Optional directory containing Jinja prompt templates. Defaults to the
-            packaged ``prompt`` directory when not provided.
-        default_model : str or None, default=None
-            Fallback model identifier when not specified elsewhere.
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use for validation.
 
         Raises
         ------
         ValueError
-            If the default model is not provided.
+            If the model is not provided.
 
         Examples
         --------
-        >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
+        >>> validator = ValidatorAgent(model="gpt-4o-mini")
         """
-        config = AgentConfiguration(
+        configuration = AgentConfiguration(
             name="validator",
             instructions="Agent instructions",
             description="Validate user input and agent output against guardrails.",
+            template_path=template_path,
             output_structure=ValidationResultStructure,
+            model=model,
         )
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(
-            config=config, prompt_dir=prompt_directory, default_model=default_model
-        )
+        super().__init__(configuration=configuration)
 
     async def run_agent(
         self,

openai_sdk_helpers/cli.py

@@ -18,17 +18,8 @@ registry inspect
 from __future__ import annotations
 
 import argparse
-import json
 import sys
 from pathlib import Path
-from typing import Any
-
-try:
-    import openai_sdk_helpers
-
-    __version__ = getattr(openai_sdk_helpers, "__version__", "unknown")
-except ImportError:
-    __version__ = "unknown"
 
 
 def cmd_agent_test(args: argparse.Namespace) -> int:
@@ -159,8 +150,8 @@ def cmd_registry_list(args: argparse.Namespace) -> int:
 
     print("Registered configurations:")
     for name in sorted(names):
-        config = registry.get(name)
-        tools_count = len(config.tools) if config.tools else 0
+        configuration = registry.get(name)
+        tools_count = len(configuration.tools) if configuration.tools else 0
         print(f"  - {name} ({tools_count} tools)")
 
     return 0
@@ -199,7 +190,7 @@ def cmd_registry_inspect(args: argparse.Namespace) -> int:
     registry = get_default_registry()
 
     try:
-        config = registry.get(args.config_name)
+        configuration = registry.get(args.config_name)
     except KeyError:
         print(f"Error: Configuration '{args.config_name}' not found", file=sys.stderr)
         print("\nAvailable configurations:")
@@ -207,17 +198,17 @@ def cmd_registry_inspect(args: argparse.Namespace) -> int:
             print(f"  - {name}")
         return 1
 
-    print(f"Configuration: {config.name}")
-    instructions_str = str(config.instructions)
+    print(f"Configuration: {configuration.name}")
+    instructions_str = str(configuration.instructions)
     instructions_preview = (
         instructions_str[:100] if len(instructions_str) > 100 else instructions_str
     )
     print(f"Instructions: {instructions_preview}...")
-    print(f"Tools: {len(config.tools) if config.tools else 0}")
+    print(f"Tools: {len(configuration.tools) if configuration.tools else 0}")
 
-    if config.tools:
+    if configuration.tools:
         print("\nTool names:")
-        for tool in config.tools:
+        for tool in configuration.tools:
             tool_name = tool.get("function", {}).get("name", "unknown")
             print(f"  - {tool_name}")
 
@@ -245,11 +236,6 @@ def main(argv: list[str] | None = None) -> int:
         prog="openai-helpers",
         description="OpenAI SDK Helpers CLI",
     )
-    parser.add_argument(
-        "--version",
-        action="version",
-        version=f"openai-sdk-helpers {__version__}",
-    )
 
     subparsers = parser.add_subparsers(dest="command", help="Commands")
 

openai_sdk_helpers/environment.py

@@ -18,8 +18,6 @@ get_data_path(name)
 
 from __future__ import annotations
 
-import os
-import os
 from pathlib import Path
 from dotenv import load_dotenv
 
@@ -61,18 +59,15 @@ def get_data_path(name: str) -> Path:
     return ensure_directory(path)
 
 
-def get_model() -> str:
-    """Return the default model identifier.
+def get_package_path() -> Path:
+    """Return the root path of the openai-sdk-helpers package.
 
     Returns
     -------
-    str
-        Default OpenAI model identifier.
-
-    Examples
-    --------
-    >>> from openai_sdk_helpers.environment import _get_default_model
-    >>> _get_default_model()
-    'gpt-4o-mini'
+    Path
+        Root directory path of the openai-sdk-helpers package.
     """
-    return os.getenv("DEFAULT_MODEL", DEFAULT_MODEL)
+    return Path(__file__).parent
+
+
+DEFAULT_PROMPT_DIR = get_package_path() / "prompt"

openai_sdk_helpers/errors.py

@@ -119,3 +119,12 @@ class ResourceCleanupError(OpenAISDKError):
     """
 
     pass
+
+
+class ExtractionError(OpenAISDKError):
+    """Extraction execution failed.
+
+    Raised when LangExtract operations fail or output validation fails.
+    """
+
+    pass

openai_sdk_helpers/extract/__init__.py

@@ -0,0 +1,23 @@
+"""LangExtract-powered document extraction helpers."""
+
+from .extractor import DocumentExtractor
+from .generator import (
+    EXTRACTOR_CONFIG_GENERATOR,
+    EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS,
+    PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS,
+    generate_document_extractor_config,
+    generate_document_extractor_config_with_agent,
+    optimize_extractor_prompt,
+    optimize_extractor_prompt_with_agent,
+)
+
+__all__ = [
+    "DocumentExtractor",
+    "EXTRACTOR_CONFIG_GENERATOR",
+    "EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS",
+    "PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS",
+    "generate_document_extractor_config",
+    "generate_document_extractor_config_with_agent",
+    "optimize_extractor_prompt",
+    "optimize_extractor_prompt_with_agent",
+]

openai_sdk_helpers/extract/extractor.py

@@ -0,0 +1,157 @@
+"""Document extraction helpers powered by LangExtract."""
+
+from __future__ import annotations
+
+import json
+import os
+import typing
+
+import langextract as lx
+from langextract.core import format_handler as lx_format_handler
+from langextract.core.data import AnnotatedDocument as LXAnnotatedDocument
+
+from ..errors import ExtractionError
+from ..structure.extraction import (
+    AnnotatedDocumentStructure,
+    DocumentStructure,
+    ExampleDataStructure,
+)
+
+
+class DocumentExtractor:
+    """Extract structured data from documents using LangExtract.
+
+    Parameters
+    ----------
+    prompt_description : str
+        Prompt description used by LangExtract.
+    examples : Sequence[ExampleDataStructure]
+        Example payloads supplied to LangExtract.
+    model_id : str
+        Model identifier to pass to LangExtract.
+    max_workers : int, optional
+        Maximum number of workers for concurrent extraction. Default is 1.
+
+    Methods
+    -------
+    extract(input_text)
+        Extract structured data from one or more documents.
+    """
+
+    def __init__(
+        self,
+        prompt_description: str,
+        examples: typing.Sequence[ExampleDataStructure],
+        model_id: str,
+        max_workers: int = 1,
+    ) -> None:
+        """Initialize the extractor.
+
+        Parameters
+        ----------
+        prompt_description : str
+            Prompt description used by LangExtract.
+        examples : Sequence[ExampleDataStructure]
+            Example payloads supplied to LangExtract.
+        model_id : str
+            Model identifier to pass to LangExtract.
+        max_workers : int, optional
+            Maximum number of workers for concurrent extraction. Default is 1.
+        """
+        if not examples:
+            raise ValueError(
+                "Examples are required for reliable extraction. "
+                "Provide at least one ExampleDataStructure instance."
+            )
+        self.model_id = model_id
+        self.prompt = prompt_description
+        self.examples = examples
+        self.max_workers = max_workers
+
+    def extract(
+        self, input_text: DocumentStructure | list[DocumentStructure]
+    ) -> list[AnnotatedDocumentStructure]:
+        """Run the extraction.
+
+        Parameters
+        ----------
+        input_text : DocumentStructure | list[DocumentStructure]
+            Document or list of documents to extract data from.
+
+        Returns
+        -------
+        list[AnnotatedDocumentStructure]
+            Extracted items for the provided documents.
+        """
+        if isinstance(input_text, DocumentStructure):
+            input_documents = [input_text]
+        else:
+            input_documents = input_text
+        documents = DocumentStructure.to_dataclass_list(input_documents)
+        examples = ExampleDataStructure.to_dataclass_list(self.examples)
+        resolver_params = {"format_handler": _SanitizingFormatHandler()}
+        result = lx.extract(
+            text_or_documents=documents,
+            prompt_description=self.prompt,
+            examples=examples,
+            model_id=self.model_id,  # Automatically selects OpenAI provider
+            api_key=os.environ.get("OPENAI_API_KEY"),
+            fence_output=True,
+            use_schema_constraints=False,
+            resolver_params=resolver_params,
+        )
+
+        def _convert(data: typing.Any) -> AnnotatedDocumentStructure:
+            if isinstance(data, LXAnnotatedDocument):
+                return AnnotatedDocumentStructure.from_dataclass(data)
+            return AnnotatedDocumentStructure.model_validate(data)
+
+        if isinstance(result, list):
+            return [_convert(doc) for doc in result]
+
+        return [_convert(result)]
+
+
+def _sanitize_extraction_items(
+    items: typing.Sequence[typing.Mapping[str, lx_format_handler.ExtractionValueType]],
+    attribute_suffix: str,
+) -> list[dict[str, lx_format_handler.ExtractionValueType]]:
+    sanitized: list[dict[str, lx_format_handler.ExtractionValueType]] = []
+    for item in items:
+        updated: dict[str, lx_format_handler.ExtractionValueType] = {}
+        for key, value in item.items():
+            keep, cleaned = _sanitize_extraction_value(key, value, attribute_suffix)
+            if not keep:
+                continue
+            updated[key] = cleaned
+        sanitized.append(updated)
+    return sanitized
+
+
+def _sanitize_extraction_value(
+    key: str,
+    value: lx_format_handler.ExtractionValueType,
+    attribute_suffix: str,
+) -> tuple[bool, lx_format_handler.ExtractionValueType]:
+    if value is None:
+        return False, None
+    if key.endswith(attribute_suffix):
+        if isinstance(value, dict):
+            return True, value
+        return False, None
+    if isinstance(value, (str, int, float)):
+        return True, value
+    return True, json.dumps(value, ensure_ascii=False)
+
+
+class _SanitizingFormatHandler(lx_format_handler.FormatHandler):
+    """Sanitize LangExtract output before the resolver validates types."""
+
+    def parse_output(
+        self, text: str, *, strict: bool | None = None
+    ) -> typing.Sequence[typing.Mapping[str, lx_format_handler.ExtractionValueType]]:
+        items = super().parse_output(text, strict=strict)
+        return _sanitize_extraction_items(items, self.attribute_suffix)
+
+
+__all__ = ["DocumentExtractor", "ExtractionError"]