Download the PHP package helgesverre/synapse without Composer

Synapse

A modern PHP 8.2+ library for LLM orchestration with executors, prompts, parsers, streaming, and tool calling. Inspired by llm-exe.

Features

• Executor Pattern: Composable execution pipeline with lifecycle hooks
• Prompt System: Template-based prompts with helpers, partials, and history
• Parser System: Extract structured data from LLM responses (JSON, boolean, lists, enums, code blocks)
• Tool/Function Calling: Built-in support for multi-step tool calling
• State Management: Conversation history and context tracking
• Streaming: Token streaming and streaming tool calls
• Multi-Provider: OpenAI, Anthropic, Google/Gemini, Mistral, xAI, Groq, Moonshot, plus local models via Ollama
• Embeddings: Unified embedding providers (OpenAI, Mistral, Jina, Cohere, Voyage, Ollama)
• Runtime Modules: Trace bridge/exporters, checkpoints, memory store, workflow engine, and evaluation suite
• Event Hooks: Lifecycle events for logging, metrics, and debugging
• PSR Standards: PSR-4, PSR-7, PSR-17, PSR-18 compatible

Installation

You'll also need an HTTP client (PSR-18) and HTTP factories (PSR-17). Synapse can auto-discover Guzzle or Symfony HTTP client if installed:

If you prefer Symfony:

Quick Start

If you want to configure transport manually:

Core Concepts

Executors

Executors are the core building blocks that orchestrate the LLM pipeline.

Prompts

Prompts use {{variable}} syntax for template replacement. Note: addUserMessage() defaults to parseTemplate: false, so pass parseTemplate: true when you want template rendering.

Template Features

Parsers

Extract structured data from LLM responses.

Tool/Function Calling

Use createToolRegistry() to register tools for function calling.

Streaming

Streaming requires a stream-capable transport (for example GuzzleStreamTransport).

See examples/streaming-cli.php and examples/streaming-chat-cli.php for full demos.

Example Index

Key examples to start with:

• examples/basic-usage.php
• examples/tool-calling.php
• examples/streaming-cli.php
• examples/agentic-agent-cli.php
• examples/profilinator2000/

Production-oriented patterns:

• examples/production/retry-and-fallback.php
• examples/production/safe-tools.php
• examples/production/persistent-dialogue-redis.php
• examples/production/http-sse-chat-endpoint.php
• examples/production/observability-hooks.php
• examples/production/testing-with-fakes.php
• examples/production/trace-bridge.php
• examples/production/checkpoints-and-memory.php
• examples/production/workflow-engine.php
• examples/production/evaluation-suite.php

State Management

Event Hooks

Embeddings

Providers

useLlm() supports the following provider prefixes:

• openai.*
• anthropic.*
• google.* / gemini.*
• mistral.*
• xai.* / grok.*
• groq.*
• moonshot.*
• ollama.* (local; no API key required, defaults to http://localhost:11434/v1)

You can set model either inline (prefix.model) or in options (['model' => '...']). Do not provide conflicting model values in both places.

OpenAI

Anthropic

Google (Gemini)

Mistral

xAI (Grok)

Groq

Moonshot

Ollama (local)

Run open-weights models locally — no API key required. Synapse uses Ollama's OpenAI-compatible endpoint at http://localhost:11434/v1.

Embeddings work the same way:

See examples/ollama-react-agent.php for a manual ReAct loop with tools running entirely against local Gemma.

Custom Provider

Implement LlmProviderInterface:

Architecture

Testing

Running Tests

Integration Tests

Integration tests require valid API keys set as environment variables:

• OPENAI_API_KEY, ANTHROPIC_API_KEY, MISTRAL_API_KEY, MOONSHOT_API_KEY, XAI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY

Tests will automatically skip if the required API key is not set.

License

MIT