openai-sdk-helpers 0.4.2__tar.gz → 0.5.0__tar.gz

{openai_sdk_helpers-0.4.2 → openai_sdk_helpers-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.4.2
+Version: 0.5.0
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: jinja2
+Requires-Dist: langextract
 Requires-Dist: openai-agents<1.0.0,>=0.6.4
 Requires-Dist: openai<3.0.0,>=2.14.0
 Requires-Dist: pydantic<3,>=2.7
@@ -31,6 +32,8 @@ Requires-Dist: pyright; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-asyncio; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
+Provides-Extra: extract
+Requires-Dist: langextract; extra == 'extract'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -78,7 +81,7 @@ structures, configuration helpers, and orchestration utilities—while leaving
 application-specific prompts and tools to the consuming project.
 
 **Important**: This library integrates with **two distinct OpenAI SDKs**:
-- **`openai-agents`** - Used by the `agent` module for high-level agent workflows with automatic tool handling and streaming
+- **`openai-agents`** - Used by the `agent` module for high-level agent workflows with automatic tool handling
 - **`openai`** - Used by the `response` module for direct API interactions with fine-grained control over responses
 
 The `agent` module provides a higher-level abstraction for building agents, while the `response` module offers lower-level control for custom response handling workflows.
@@ -193,10 +196,11 @@ report = vector_search.run_agent_sync("Explain quantum entanglement for beginner
 print(report.report)
 ```
 
-**Note**: The vector search workflow requires prompt templates for each agent
-(`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`). 
-If your `prompt_dir` doesn't contain these files, agent construction will fail 
-with a `FileNotFoundError`.
+**Note**: The vector search workflow ships with default prompt templates
+(`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`).
+You only need to pass a `prompt_dir` when you want to override them; if the
+directory you supply is missing any of the templates, agent construction will
+fail with a `FileNotFoundError`.
 
 ### Text utilities
 
@@ -301,7 +305,7 @@ response.close()
 ```
 
 **Key Differences:**
-- **Agent Module**: Higher-level abstraction with built-in streaming, automatic tool handling, and agent-specific workflows
+- **Agent Module**: Higher-level abstraction with automatic tool handling and agent-specific workflows
 - **Response Module**: Lower-level control with manual message management, custom tool handlers, and direct API access
 
 ## Advanced Usage
@@ -510,7 +514,7 @@ src/openai_sdk_helpers/
 │   ├── summary.py     # Summary output structures
 │   └── validation.py  # Validation result structures
 ├── vector_storage/     # Vector store abstraction layer
-├── config.py          # OpenAI settings and configuration
+├── configuration.py          # OpenAI settings and configuration
 └── utils/             # JSON serialization, logging, and helpers
 
 tests/                  # Comprehensive unit test suite
@@ -522,7 +526,7 @@ The package is organized around cohesive, reusable building blocks:
 
 ### Agent Modules (Built on `openai-agents` SDK)
 
-These modules use the `openai-agents` SDK for high-level agent workflows with automatic streaming, tool handling, and conversation management.
+These modules use the `openai-agents` SDK for high-level agent workflows with automatic tool handling and conversation management.
 
 - **`openai_sdk_helpers.agent.base.AgentBase`**  
   Base class for all agents with synchronous and asynchronous execution support.
@@ -562,7 +566,7 @@ These modules use the standard `openai` SDK for direct API interactions with fin
 
 ### Configuration and Data Structures (Shared)
 
-- **`openai_sdk_helpers.config.OpenAISettings`**  
+- **`openai_sdk_helpers.settings.OpenAISettings`**  
   Centralizes OpenAI API configuration with environment variable support.
   Creates configured OpenAI clients with consistent settings.
 
@@ -584,6 +588,17 @@ These modules use the standard `openai` SDK for direct API interactions with fin
 - **`openai_sdk_helpers.utils`**  
   JSON serialization helpers, logging utilities, and common validation functions.
 
+- **`openai_sdk_helpers.utils.langextract`**  
+  Adapter helpers for running LangExtract-style extractors and validating the
+  results into Pydantic models.
+
+## Related Projects
+
+- **[LangExtract](https://github.com/google/langextract)**  
+  Google-maintained toolkit for extracting structured data from language model
+  outputs, which can complement the validation and response utilities in
+  `openai-sdk-helpers`.
+
 ## Contributing
 
 Contributions are welcome! We appreciate functional changes accompanied by
@@ -696,4 +711,3 @@ recognizing types:
 - Check the [Key Modules](#key-modules) section for API documentation
 - Review examples in the [Quickstart](#quickstart) and [Advanced Usage](#advanced-usage) sections
 - Open an issue on GitHub for bugs or feature requests
-

{openai_sdk_helpers-0.4.2 → openai_sdk_helpers-0.5.0}/README.md

@@ -43,7 +43,7 @@ structures, configuration helpers, and orchestration utilities—while leaving
 application-specific prompts and tools to the consuming project.
 
 **Important**: This library integrates with **two distinct OpenAI SDKs**:
-- **`openai-agents`** - Used by the `agent` module for high-level agent workflows with automatic tool handling and streaming
+- **`openai-agents`** - Used by the `agent` module for high-level agent workflows with automatic tool handling
 - **`openai`** - Used by the `response` module for direct API interactions with fine-grained control over responses
 
 The `agent` module provides a higher-level abstraction for building agents, while the `response` module offers lower-level control for custom response handling workflows.
@@ -158,10 +158,11 @@ report = vector_search.run_agent_sync("Explain quantum entanglement for beginner
 print(report.report)
 ```
 
-**Note**: The vector search workflow requires prompt templates for each agent
-(`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`). 
-If your `prompt_dir` doesn't contain these files, agent construction will fail 
-with a `FileNotFoundError`.
+**Note**: The vector search workflow ships with default prompt templates
+(`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`).
+You only need to pass a `prompt_dir` when you want to override them; if the
+directory you supply is missing any of the templates, agent construction will
+fail with a `FileNotFoundError`.
 
 ### Text utilities
 
@@ -266,7 +267,7 @@ response.close()
 ```
 
 **Key Differences:**
-- **Agent Module**: Higher-level abstraction with built-in streaming, automatic tool handling, and agent-specific workflows
+- **Agent Module**: Higher-level abstraction with automatic tool handling and agent-specific workflows
 - **Response Module**: Lower-level control with manual message management, custom tool handlers, and direct API access
 
 ## Advanced Usage
@@ -475,7 +476,7 @@ src/openai_sdk_helpers/
 │   ├── summary.py     # Summary output structures
 │   └── validation.py  # Validation result structures
 ├── vector_storage/     # Vector store abstraction layer
-├── config.py          # OpenAI settings and configuration
+├── configuration.py          # OpenAI settings and configuration
 └── utils/             # JSON serialization, logging, and helpers
 
 tests/                  # Comprehensive unit test suite
@@ -487,7 +488,7 @@ The package is organized around cohesive, reusable building blocks:
 
 ### Agent Modules (Built on `openai-agents` SDK)
 
-These modules use the `openai-agents` SDK for high-level agent workflows with automatic streaming, tool handling, and conversation management.
+These modules use the `openai-agents` SDK for high-level agent workflows with automatic tool handling and conversation management.
 
 - **`openai_sdk_helpers.agent.base.AgentBase`**  
   Base class for all agents with synchronous and asynchronous execution support.
@@ -527,7 +528,7 @@ These modules use the standard `openai` SDK for direct API interactions with fin
 
 ### Configuration and Data Structures (Shared)
 
-- **`openai_sdk_helpers.config.OpenAISettings`**  
+- **`openai_sdk_helpers.settings.OpenAISettings`**  
   Centralizes OpenAI API configuration with environment variable support.
   Creates configured OpenAI clients with consistent settings.
 
@@ -549,6 +550,17 @@ These modules use the standard `openai` SDK for direct API interactions with fin
 - **`openai_sdk_helpers.utils`**  
   JSON serialization helpers, logging utilities, and common validation functions.
 
+- **`openai_sdk_helpers.utils.langextract`**  
+  Adapter helpers for running LangExtract-style extractors and validating the
+  results into Pydantic models.
+
+## Related Projects
+
+- **[LangExtract](https://github.com/google/langextract)**  
+  Google-maintained toolkit for extracting structured data from language model
+  outputs, which can complement the validation and response utilities in
+  `openai-sdk-helpers`.
+
 ## Contributing
 
 Contributions are welcome! We appreciate functional changes accompanied by
@@ -661,4 +673,3 @@ recognizing types:
 - Check the [Key Modules](#key-modules) section for API documentation
 - Review examples in the [Quickstart](#quickstart) and [Advanced Usage](#advanced-usage) sections
 - Open an issue on GitHub for bugs or feature requests
-

{openai_sdk_helpers-0.4.2 → openai_sdk_helpers-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.4.2"
+version = "0.5.0"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"
@@ -36,7 +36,8 @@ dependencies = [
     # OpenAI functionality (tested with openai==2.14.0, openai-agents==0.6.4)
     "openai>=2.14.0,<3.0.0",
     "openai-agents>=0.6.4,<1.0.0",
-
+    # Language extraction
+    "langextract",
 
     # Web UI
     "streamlit",
@@ -57,6 +58,9 @@ dev = [
     "pytest",
     "pytest-asyncio",
 ]
+extract = [
+    "langextract",
+]
 
 [build-system]
 requires = ["hatchling"]

{openai_sdk_helpers-0.4.2 → openai_sdk_helpers-0.5.0}/src/openai_sdk_helpers/__init__.py

@@ -2,15 +2,9 @@
 
 from __future__ import annotations
 
-from .environment import get_data_path, get_model
+from .environment import get_data_path
 from .utils.async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
-from .context_manager import (
-    AsyncManagedResource,
-    ManagedResource,
-    async_context,
-    ensure_closed,
-    ensure_closed_async,
-)
+
 from .errors import (
     OpenAISDKError,
     ConfigurationError,
@@ -22,8 +16,9 @@ from .errors import (
     InputValidationError,
     AsyncExecutionError,
     ResourceCleanupError,
+    ExtractionError,
 )
-from .retry import with_exponential_backoff
+
 from .utils.validation import (
     validate_choice,
     validate_dict_mapping,
@@ -46,12 +41,17 @@ from .structure import (
     ExtendedSummaryStructure,
     ValidationResultStructure,
     AgentBlueprint,
+    AnnotatedDocumentStructure,
+    AttributeStructure,
+    DocumentStructure,
+    ExampleDataStructure,
+    ExtractionStructure,
     create_plan,
     execute_task,
     execute_plan,
 )
 from .prompt import PromptRenderer
-from .config import OpenAISettings
+from .settings import OpenAISettings
 from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
@@ -73,22 +73,17 @@ from .response import (
     ResponseConfiguration,
     ResponseRegistry,
     get_default_registry,
-    parse_tool_arguments,
     attach_vector_store,
 )
 from .tools import (
-    serialize_tool_result,
     tool_handler_factory,
     StructureType,
+    ToolHandler,
+    ToolHandlerRegistration,
     ToolSpec,
-    build_tool_definitions,
-)
-from .config import build_openai_settings
-from .utils.deprecation import (
-    deprecated,
-    warn_deprecated,
-    DeprecationHelper,
+    build_tool_definition_list,
 )
+from .settings import build_openai_settings
 from .utils.output_validation import (
     ValidationResult,
     ValidationRule,
@@ -98,15 +93,21 @@ from .utils.output_validation import (
     OutputValidator,
     validate_output,
 )
-from .types import (
-    SupportsOpenAIClient,
-    OpenAIClient,
+from .utils.langextract import LangExtractAdapter, build_langextract_adapter
+from .extract import (
+    DocumentExtractor,
+    EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS,
+    EXTRACTOR_CONFIG_GENERATOR,
+    PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS,
+    generate_document_extractor_config,
+    generate_document_extractor_config_with_agent,
+    optimize_extractor_prompt,
+    optimize_extractor_prompt_with_agent,
 )
 
 __all__ = [
     # Environment utilities
     "get_data_path",
-    "get_model",
     # Async utilities
     "run_coroutine_thread_safe",
     "run_coroutine_with_fallback",
@@ -121,14 +122,7 @@ __all__ = [
     "InputValidationError",
     "AsyncExecutionError",
     "ResourceCleanupError",
-    # Retry utilities
-    "with_exponential_backoff",
-    # Context managers
-    "ManagedResource",
-    "AsyncManagedResource",
-    "ensure_closed",
-    "ensure_closed_async",
-    "async_context",
+    "ExtractionError",
     # Validation
     "validate_non_empty_string",
     "validate_max_length",
@@ -166,6 +160,11 @@ __all__ = [
     "WebSearchStructure",
     "VectorSearchStructure",
     "ValidationResultStructure",
+    "AnnotatedDocumentStructure",
+    "AttributeStructure",
+    "DocumentStructure",
+    "ExampleDataStructure",
+    "ExtractionStructure",
     "ResponseBase",
     "ResponseMessage",
     "ResponseMessages",
@@ -173,24 +172,17 @@ __all__ = [
     "ResponseConfiguration",
     "ResponseRegistry",
     "get_default_registry",
-    "parse_tool_arguments",
     "attach_vector_store",
-    "serialize_tool_result",
     "tool_handler_factory",
     "StructureType",
+    "ToolHandler",
+    "ToolHandlerRegistration",
     "ToolSpec",
-    "build_tool_definitions",
+    "build_tool_definition_list",
     "build_openai_settings",
     "create_plan",
     "execute_task",
     "execute_plan",
-    # Type definitions
-    "SupportsOpenAIClient",
-    "OpenAIClient",
-    # Deprecation utilities
-    "deprecated",
-    "warn_deprecated",
-    "DeprecationHelper",
     # Output validation
     "ValidationResult",
     "ValidationRule",
@@ -199,4 +191,16 @@ __all__ = [
     "LengthValidator",
     "OutputValidator",
     "validate_output",
+    # LangExtract
+    "LangExtractAdapter",
+    "build_langextract_adapter",
+    # Extraction helpers
+    "DocumentExtractor",
+    "EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS",
+    "EXTRACTOR_CONFIG_GENERATOR",
+    "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-0.4.2 → openai_sdk_helpers-0.5.0}/src/openai_sdk_helpers/agent/__init__.py

@@ -1,16 +1,15 @@
 """Shared agent helpers built on the OpenAI Agents SDK."""
 
 from __future__ import annotations
-
 from .base import AgentBase
-from .config import AgentConfiguration, AgentRegistry, get_default_registry
+from .configuration import AgentConfiguration, AgentRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
-from .coordination import CoordinatorAgent
-from .runner import run_sync, run_async, run_streamed
+from .coordinator import CoordinatorAgent
+from .runner import run_sync, run_async
 from .search.base import SearchPlanner, SearchToolAgent, SearchWriter
 from .summarizer import SummarizerAgent
 from .translator import TranslatorAgent
-from .validation import ValidatorAgent
+from .validator import ValidatorAgent
 from .utils import run_coroutine_agent_sync
 from .search.vector import VectorAgentSearch
 from .search.web import WebAgentSearch
@@ -24,7 +23,6 @@ __all__ = [
     "CoordinatorAgent",
     "run_sync",
     "run_async",
-    "run_streamed",
     "run_coroutine_agent_sync",
     "SearchPlanner",
     "SearchToolAgent",