openai-sdk-helpers 0.0.2__tar.gz → 0.0.3__tar.gz

{openai_sdk_helpers-0.0.2 → openai_sdk_helpers-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.0.2
+Version: 0.0.3
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT
@@ -39,6 +39,7 @@ application-specific prompts and tools to the consuming project.
   predictable inputs and outputs.
 - **Vector and web search flows** that coordinate planning, execution, and
   reporting.
+- **Reusable text agents** for summarization and translation tasks.
 
 ## Installation
 
@@ -48,6 +49,9 @@ Install the package directly from PyPI to reuse it across projects:
 pip install openai-sdk-helpers
 ```
 
+Type information ships with the published wheel via `py.typed`, so external
+projects can rely on the bundled annotations without adding custom stubs.
+
 For local development, install with editable sources and the optional dev
 dependencies:
 
@@ -74,9 +78,39 @@ report = vector_search.run_agent_sync("Explain quantum entanglement for beginner
 print(report.report)
 ```
 
-You can plug in your own prompt templates by placing matching `.jinja` files in
-the provided `prompt_dir` and naming them after the agent (for example,
-`vector_planner.jinja`).
+### Text utilities
+
+Use the built-in text helpers when you need lightweight single-step agents.
+
+```python
+from openai_sdk_helpers.agent import (
+    SummarizerAgent,
+    TranslatorAgent,
+    ValidatorAgent,
+)
+
+
+summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+translator = TranslatorAgent(default_model="gpt-4o-mini")
+validator = ValidatorAgent(default_model="gpt-4o-mini")
+
+summary = summarizer.run_sync("Long-form content to condense")
+translation = translator.run_sync("Bonjour", target_language="English")
+guardrails = validator.run_sync(
+    "Share meeting notes with names removed", agent_output=summary.text
+)
+```
+
+Prompt templates are optional for the built-in text helpers. They already ship
+with defaults under `src/openai_sdk_helpers/prompt`, so you do **not** need to
+create placeholder files when installing from PyPI. Only pass a `prompt_dir`
+when you have real replacements you want to load.
+
+The vector search workflow expects real prompts for each agent (for example,
+`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`). If
+you point `prompt_dir` at a folder that does not contain those files, agent
+construction fails with a `FileNotFoundError`. Skip `prompt_dir` entirely unless
+you have working templates ready.
 
 ### Centralized OpenAI configuration
 
@@ -129,6 +163,25 @@ pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70
 - `src/openai_sdk_helpers/vector_storage`: Minimal vector store abstraction.
 - `tests/`: Unit tests covering core modules and structures.
 
+## Key modules
+
+The package centers around a handful of cohesive building blocks:
+
+- `openai_sdk_helpers.agent.project_manager.ProjectManager` coordinates prompt
+  creation, plan building, task execution, and summarization while persisting
+  intermediate artifacts to disk.
+- `openai_sdk_helpers.agent.vector_search.VectorSearch` bundles the planners,
+  executors, and summarizers required to run a multi-turn vector search flow
+  from a single entry point.
+- `openai_sdk_helpers.agent.summarizer.SummarizerAgent`,
+  `agent.translator.TranslatorAgent`, and `agent.validator.ValidatorAgent`
+  expose streamlined text-processing utilities that reuse shared prompt
+  templates.
+- `openai_sdk_helpers.response` contains the response runners and helpers used
+  to normalize outputs from agents, including streaming responses.
+- `openai_sdk_helpers.utils` holds JSON serialization helpers, logging
+  utilities, and common validation helpers used across modules.
+
 ## Contributing
 
 Contributions are welcome! Please accompany functional changes with relevant

{openai_sdk_helpers-0.0.2 → openai_sdk_helpers-0.0.3}/README.md

@@ -23,6 +23,7 @@ application-specific prompts and tools to the consuming project.
   predictable inputs and outputs.
 - **Vector and web search flows** that coordinate planning, execution, and
   reporting.
+- **Reusable text agents** for summarization and translation tasks.
 
 ## Installation
 
@@ -32,6 +33,9 @@ Install the package directly from PyPI to reuse it across projects:
 pip install openai-sdk-helpers
 ```
 
+Type information ships with the published wheel via `py.typed`, so external
+projects can rely on the bundled annotations without adding custom stubs.
+
 For local development, install with editable sources and the optional dev
 dependencies:
 
@@ -58,9 +62,39 @@ report = vector_search.run_agent_sync("Explain quantum entanglement for beginner
 print(report.report)
 ```
 
-You can plug in your own prompt templates by placing matching `.jinja` files in
-the provided `prompt_dir` and naming them after the agent (for example,
-`vector_planner.jinja`).
+### Text utilities
+
+Use the built-in text helpers when you need lightweight single-step agents.
+
+```python
+from openai_sdk_helpers.agent import (
+    SummarizerAgent,
+    TranslatorAgent,
+    ValidatorAgent,
+)
+
+
+summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+translator = TranslatorAgent(default_model="gpt-4o-mini")
+validator = ValidatorAgent(default_model="gpt-4o-mini")
+
+summary = summarizer.run_sync("Long-form content to condense")
+translation = translator.run_sync("Bonjour", target_language="English")
+guardrails = validator.run_sync(
+    "Share meeting notes with names removed", agent_output=summary.text
+)
+```
+
+Prompt templates are optional for the built-in text helpers. They already ship
+with defaults under `src/openai_sdk_helpers/prompt`, so you do **not** need to
+create placeholder files when installing from PyPI. Only pass a `prompt_dir`
+when you have real replacements you want to load.
+
+The vector search workflow expects real prompts for each agent (for example,
+`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`). If
+you point `prompt_dir` at a folder that does not contain those files, agent
+construction fails with a `FileNotFoundError`. Skip `prompt_dir` entirely unless
+you have working templates ready.
 
 ### Centralized OpenAI configuration
 
@@ -113,6 +147,25 @@ pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70
 - `src/openai_sdk_helpers/vector_storage`: Minimal vector store abstraction.
 - `tests/`: Unit tests covering core modules and structures.
 
+## Key modules
+
+The package centers around a handful of cohesive building blocks:
+
+- `openai_sdk_helpers.agent.project_manager.ProjectManager` coordinates prompt
+  creation, plan building, task execution, and summarization while persisting
+  intermediate artifacts to disk.
+- `openai_sdk_helpers.agent.vector_search.VectorSearch` bundles the planners,
+  executors, and summarizers required to run a multi-turn vector search flow
+  from a single entry point.
+- `openai_sdk_helpers.agent.summarizer.SummarizerAgent`,
+  `agent.translator.TranslatorAgent`, and `agent.validator.ValidatorAgent`
+  expose streamlined text-processing utilities that reuse shared prompt
+  templates.
+- `openai_sdk_helpers.response` contains the response runners and helpers used
+  to normalize outputs from agents, including streaming responses.
+- `openai_sdk_helpers.utils` holds JSON serialization helpers, logging
+  utilities, and common validation helpers used across modules.
+
 ## Contributing
 
 Contributions are welcome! Please accompany functional changes with relevant

{openai_sdk_helpers-0.0.2 → openai_sdk_helpers-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.0.2"
+version = "0.0.3"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"
@@ -49,6 +49,12 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build]
+include = [
+    "src/openai_sdk_helpers/prompt/*.jinja",
+    "src/openai_sdk_helpers/py.typed",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/openai_sdk_helpers"]
 

openai_sdk_helpers-0.0.3/src/openai_sdk_helpers/prompt/summarizer.jinja

@@ -0,0 +1,7 @@
+You are a concise assistant that summarizes long-form text into crisp findings.
+
+Instructions:
+- Focus on factual statements present in the source text.
+- Prefer short bullet points over paragraphs.
+- Call out key entities, dates, and figures when present.
+- Note any missing context or unanswered questions.

openai_sdk_helpers-0.0.3/src/openai_sdk_helpers/prompt/translator.jinja

@@ -0,0 +1,7 @@
+You are a professional translator.
+
+Instructions:
+- Rewrite the provided text into the requested target language.
+- Preserve the intent and meaning of the original content.
+- Keep terminology consistent and avoid embellishment.
+- If the input text is empty, respond with "No text provided."

openai_sdk_helpers-0.0.3/src/openai_sdk_helpers/prompt/validator.jinja

@@ -0,0 +1,7 @@
+You are a meticulous safety validator that enforces product guardrails.
+
+Instructions:
+- Inspect the provided user_input and optional agent_output for policy violations, safety risks, or missing disclaimers.
+- Highlight any prohibited content (violence, hate, sensitive data, PII) and note why it violates guardrails.
+- Recommend concise remediation steps (redaction, refusal, rephrasing) and provide sanitized_output when possible.
+- If everything is within guardrails, confirm both input_safe and output_safe are true and keep violations empty.

openai_sdk_helpers-0.0.2/.github/dependabot.yml

@@ -1,10 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-version: 2
-updates:
-  - package-ecosystem: "" # See documentation for possible values
-    directory: "/" # Location of package manifests
-    schedule:
-      interval: "weekly"

openai_sdk_helpers-0.0.2/.github/workflows/ci.yml

@@ -1,44 +0,0 @@
-name: Python CI
-
-on:
-  push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
-
-    steps:
-    - uses: actions/checkout@v3
-
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ matrix.python-version }}
-        cache: "pip"
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -e . --group dev
-
-    - name: Run style checks
-      run: |
-        pydocstyle .
-        black --check .
-
-    - name: Run static type analysis
-      run: |
-        pyright .
-
-    - name: Run tests with coverage
-      run: |
-        pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70

openai_sdk_helpers-0.0.2/.github/workflows/python-publish.yml

@@ -1,39 +0,0 @@
-# This workflow will upload a Python Package using Twine when a release is created
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
-
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
-name: Upload Python Package
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  deploy:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build
-    - name: Build package
-      run: python -m build
-    - name: Publish package
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_API_TOKEN }}

openai_sdk_helpers-0.0.2/AGENTS.md

@@ -1,82 +0,0 @@
-# AGENTS.md
-
-These instructions apply to any automated agent contributing to this repository.
-
-## 1. Code Style
-
-- Use standard PEP 8 formatting for all Python code.
-- Write commit messages in the imperative mood (e.g., "Add feature" not "Added feature").
-- Keep the implementation Pythonic and maintainable.
-
-## 2. Docstring Style
-
-- Use **NumPy-style** docstrings following [PEP 257](https://peps.python.org/pep-0257/) conventions.
-- **Do not** use `:param` / `:type` syntax (reST/Sphinx style) or Google-style `Args`.
-- Always include type hints in function signatures.
-- Begin docstrings with a **short, one-line summary**, followed by a blank line and an optional extended description.
-- Use the following NumPy-style sections:
-  - `Parameters`
-  - `Returns`
-  - `Raises`
-  - `Examples`
-- Document all public classes, methods, and functions.
-- **For classes, the main docstring should include a `Methods` section summarizing each public method and its one-line description.**
-- For optional parameters, note the default value in the description.
-- Use imperative present tense and active voice (“Return…”, “Fetch…”).
-
-## 3. Code Quality and Testing
-
-Before running tests, install the development dependencies:
-
-```bash
-# Install the package with dev dependency group (PEP 735)
-pip install -e . --group dev
-```
-
-To ensure your changes will pass the automated checks in our Continuous Integration (CI) pipeline, run the following commands locally before committing. All checks must pass.
-
-**Style Checks:**
-```bash
-pydocstyle src
-black --check .
-```
-
-**Static Type Analysis:**
-```bash
-pyright src
-```
-
-**Unit Tests and Coverage:**
-```bash
-pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70
-```
-
-## 4. Directory Layout
-
-- Production code lives in `src/`.
-- Tests live in `tests/`.
-- Keep imports relative within the package (e.g., `from rda_bundle...`).
-
-## 5. Pull Request Messages
-
-Each pull request should include:
-
-1. **Summary** – brief description of the change.
-2. **Testing** – commands run and confirmation that the tests passed.
-
-Example PR body:
-
-```
-### Summary
-- add new helper to utils.list
-- expand tests for list chunking
-
-### Testing
-- `pytest` (all tests passed)
-```
-
-## 6. General Guidelines
-
-- Avoid pushing large data files to the repository.
-- Prefer small, focused commits over sweeping changes.
-- Update or add tests whenever you modify functionality.

openai_sdk_helpers-0.0.2/src/openai_sdk_helpers/__init__.py

@@ -1,34 +0,0 @@
-"""Shared AI helpers and base structures."""
-
-from __future__ import annotations
-
-__version__ = "0.0.1"
-
-from .structure import (
-    BaseStructure,
-    SchemaOptions,
-    spec_field,
-    assistant_tool_definition,
-    assistant_format,
-    response_tool_definition,
-    response_format,
-)
-from .prompt import PromptRenderer
-from .config import OpenAISettings
-from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
-
-__all__ = [
-    "__version__",
-    "BaseStructure",
-    "SchemaOptions",
-    "spec_field",
-    "PromptRenderer",
-    "OpenAISettings",
-    "VectorStorage",
-    "VectorStorageFileInfo",
-    "VectorStorageFileStats",
-    "assistant_tool_definition",
-    "assistant_format",
-    "response_tool_definition",
-    "response_format",
-]

openai_sdk_helpers-0.0.2/src/openai_sdk_helpers/agent/__init__.py

@@ -1,23 +0,0 @@
-"""Shared agent helpers built on the OpenAI Agents SDK."""
-
-from __future__ import annotations
-
-from .base import BaseAgent
-from .config import AgentConfig
-from .project_manager import ProjectManager
-from .runner import run, run_streamed, run_sync
-from .utils import run_coro_sync
-from .vector_search import VectorSearch
-from .web_search import WebAgentSearch
-
-__all__ = [
-    "BaseAgent",
-    "AgentConfig",
-    "ProjectManager",
-    "run",
-    "run_sync",
-    "run_streamed",
-    "run_coro_sync",
-    "VectorSearch",
-    "WebAgentSearch",
-]