v1.15.0

✨ New Features

OpenAI Responses API Support

Hayhooks now supports the OpenAI Responses API (/v1/responses) alongside the existing Chat Completions API. Pipeline wrappers can implement run_response or run_response_async to handle Responses API requests — with full support for streaming (named SSE events), non-streaming, and async modes.

This makes Hayhooks compatible with clients that use the Responses API wire format, such as the OpenAI Codex CLI.

class PipelineWrapper(BasePipelineWrapper):
    def setup(self) -> None:
        self.pipeline = Pipeline.loads(...)

    def run_response(self, model: str, input_items: list[dict], body: dict) -> str | Generator:
        question = get_last_user_input_text(input_items)
        result = self.pipeline.run({"prompt_builder": {"question": question}})
        return result["llm"]["replies"][0].text

See the examples:

• responses_with_file_upload — Responses API with file uploads
• agent_codex — Hybrid tool-calling with Codex CLI (client-side tools + server-side enrichment)
• chat_completion_with_file_upload — Chat Completions API with file uploads

Files API (/v1/files)

A new /v1/files endpoint lets clients upload files for use with the Responses API. Pipeline wrappers can override run_file_upload to store or process uploaded files. If no wrapper implements file handling, Hayhooks returns a stub FileObject with a warning — so the endpoint is always available.

Responses API Utilities

New public utility functions make it easy to work with Responses API input items inside pipeline wrappers:

Utility	Description
get_last_user_input_text(input_items)	Extract the last user text from Responses API input items
get_input_files(input_items)	Extract all input_file content parts from input items
chat_messages_from_openai_response(input_items)	Convert Responses API input items to Haystack ChatMessage objects (including function_call / function_call_output round-trips)

All three are exported from the top-level hayhooks package.

🏗️ Internal Improvements

Refactored OpenAI Router

The OpenAI router has been refactored from a single create_openai_router call into four composable sub-routers (create_models_router, create_chat_completion_router, create_responses_router, create_files_router), powered by the upgraded fastapi-openai-compat >= 1.1.0 dependency. Shared dispatch logic is consolidated in a single _run_pipeline_method helper, reducing duplication between Chat Completions and Responses code paths.

Smarter Stream Handling

When a pipeline wrapper returns a plain str but the client requested stream=True, Hayhooks now automatically wraps the string in a single-chunk generator instead of failing. This means non-streaming wrappers work transparently with streaming clients.

📚 Documentation

• Added Development Best Practices guide — tips for local development, debugging, logging, and testing
• Added Production Best Practices guide — CORS lockdown, health checks, structured logging, secret management, and more
• Expanded OpenAI Compatibility docs with Responses API, Files API, and utility function reference
• New Codex CLI integration example (agent_codex) — demonstrates hybrid tool-calling where Codex owns client-side tools and Hayhooks enriches with server-side tools
• New file upload examples for both Chat Completions and Responses API

🔧 CI

• Pinned all GitHub Actions to specific commit SHAs for supply-chain security (#231)

---

What's Changed

• chore: pin GitHub Actions to specific commit SHAs by @julian-risch in #231
• Add OpenAI Responses API and Files API support by @mpangrazzi in #230

Full Changelog: v1.14.0...v1.15.0