Download the PHP package bluefission/synthetiq without Composer

SynthetIQ

SynthetIQ is a lightweight conversational library for building simple, low-cost chat experiences. It sits between rigid, scripted workflows and heavy generative systems by combining intent routing, template responses, and small-scale text prediction. The goal is flexible, consistent conversation for help systems, sales assistance, and low-risk dialogue where reliability matters more than creativity.

Design Intent

• Keep responses predictable and low-cost by using templates and intent routing.
• Allow lightweight variation and continuity with a small Markov predictor.
• Favor consistent, repeatable behavior over unconstrained generation.
• Lean on BlueFission Develation and Automata objects for language, decision, and context utilities.
• See docs/automata-capability-audit.md for the current upstream capability matrix, dependency baseline, and package ownership boundaries.

How It Works

1. Input is interpreted by an Automata language interpreter.
2. Intents are classified via Automata analyzers and keyword matching.
3. Responses are generated from templates attached to those intents.
4. A decision tree and trigram Markov predictor score and select a response.
5. Conversation history and context update for follow-up turns.
6. Optional memory and fallback hooks can bias intent selection or route to a low-confidence fallback.
7. Optional spell correction can normalize near-miss tokens before routing.

Install

SynthetIQ targets PHP 8.2 or newer.

Quick Start

See example.php for a CLI and browser demo.

Examples

• examples/support.php provides the shared sample bootstrap used by the examples.
• example.php runs a small browser and CLI demo that returns response envelopes.
• examples/cli.php runs a CLI-only loop with the sample configs and current route trainer.
• examples/minimal.php shows a small custom routing setup for quick experiments.
• examples/batch.php runs a fixed number of inputs from sample_configs/statements.php.
• examples/sequence.php runs curated multi-turn batches and reports selected intents.
• examples/envelope.php prints the structured response envelope, fallback state, correction metadata, and predictor diagnostics.
• examples/evaluator.php runs an intent accuracy report through the current envelope API.
• examples/route_state.php compiles, saves, loads, verifies, and applies cached route state.
• examples/jenss/ contains optional JenSS stress fixtures for declarative route catalogs and feedback gates.
• sample_configs/conversation_scenes.php contains deterministic scene contract examples.

Useful smoke commands:

Client Configuration

Third-party clients for news/weather/location are configured in sample_configs/clients.php. These rely on the Composer package bluefission/simpleclients. External weather and news clients are disabled by default in the sample config so clean installs do not require credentials or app globals.

Use BlueFission\SynthetIQ\Clients\ClientResolver to wire optional clients explicitly:

The sample config includes null clients for clean installs and lists the SimpleClients bindings that can be enabled by changing the enabled and bindings entries. A local fake-client example is available:

Core Components

• BlueFission\SynthetIQ\SynthetIQ: orchestrates interpretation, intent classification, response generation, and selection.
• BlueFission\SynthetIQ\Intents\IntelligenceRouter: combines matcher, keyword overlap, and optional Naive Bayes strategies.
• BlueFission\SynthetIQ\Intents\Classifier: provides baseline intent matching and fallback keyword checks.
• BlueFission\SynthetIQ\Responses\Generator: renders template-based responses.
• BlueFission\SynthetIQ\Responses\Selector: selects responses using a decision tree and prediction heuristics.
• BlueFission\SynthetIQ\ConversationHistory: stores input/response pairs.
• BlueFission\SynthetIQ\Skills\*: optional Automata skills for common responses.
• BlueFission\SynthetIQ\Memory\*: pluggable short-term memory adapters.
• BlueFission\SynthetIQ\Fallback\*: low-confidence fallback responders.

Memory Recall

Memory adapters can bias intent routing and provide response-selection context. processInputEnvelope() includes recalled entries and a memory.selection summary showing which recalled episodes matched the selected response or response intent. Scope, permission checks, retrieval limits, and similarity thresholds remain adapter-owned.

See docs/memory-response-selection.md for the envelope fields and adapter responsibilities.

Routing and Templates

Routes are built by registering statements for an intent label. Each statement becomes:

• an intent keyword hint,
• a response template, and
• training data for the trigram predictor.

This keeps behavior simple, repeatable, and easy to customize.

RouteTrainer centralizes route catalog registration, boost keyword handling, progress events, stable cache-key generation, and compiled route-state serialization:

The route-state example can be used as a non-interactive rollout smoke command:

Intent Routing Strategies

SynthetIQ uses IntelligenceRouter by default. The router trains lightweight strategies from registered route keywords, combines their scores, and exposes diagnostics for review:

For direct router use:

Response Predictor Diagnostics

Response selection uses a bounded trigram predictor when available. The public diagnostic contract reports whether that predictor is available, disabled, unavailable, or failed, and whether response selection had to fall back to a candidate response:

Use setResponsePredictor(null) to disable predictor-assisted selection while keeping template selection compatible. Custom predictors can expose predictNextWords, predictNextWord, or predictBeginning.

Local Model Fallback

LocalModelFallbackResponder provides an opt-in adapter contract for unknown or low-confidence turns. Hosts provide a FallbackProviderInterface; SynthetIQ captures prompts, responses, fallback reasons, confidence, selected intent metadata, and candidate review status through TrainingCandidateStore.

The default fallback remains disabled unless explicitly configured. See docs/llm-fallback-training.md and sample_configs/fallback_training.php.

Response Envelope

processInput(string) still returns the selected response string. Use processInputEnvelope(string) when callers need structured diagnostics for a turn:

The envelope includes the response text, raw and normalized input, classified intent label, confidence, score map, selected response route, fallback state, memory recall summary, correction metadata, and response predictor diagnostics.

Use classifyInput() when evaluating or tooling only needs the classified intent and should not generate a response or append to conversation history.

Scripted Template Blocks

Response templates support opt-in {=...} blocks for bounded dynamic values. The renderer resolves input, intent, and context.* paths plus the safe transforms upper, lower, trim, and capitalize. It does not execute arbitrary PHP or external scripts.

When disabled, scripted blocks remain literal text. See docs/scripted-templates.md and sample_configs/scripted_templates.php.

Policy Filters And Audit

Policy filters can inspect input and output text around the deterministic pipeline. Denied input returns a configured replacement response; denied output can replace the selected response. Response envelopes include policy status and the structured audit trail.

Use setAuditRedactor() to redact audit payloads before they are recorded. See docs/policy-audit.md for the contract and boundary notes.

Conversation Flow Graphs

BlueFission\SynthetIQ\Flow\ConversationFlow defines explicit multi-turn states, allowed intents, transitions, fallback intents, and completion state. Attach a flow to constrain routing while a task is active:

Flows can be reset, completed, or abandoned through SynthetIQ methods.

Conversation State

BlueFission\SynthetIQ\State\ConversationState stores persona, mood, tone, task slots, session metadata, and turn summaries. SynthetIQ applies this state to the Automata context before each turn so routing, memory metadata, and response templates can read it without app globals:

Conversation Profiles and Context Handoff

ConversationProfile, ProfileRegistry, ContextEnvelope, and ContextHandoff provide a bounded transfer contract for deterministic conversational agents. Profiles declare supported intents, capabilities, and permitted context-reference categories; undeclared context is redacted before an accepted handoff.

See docs/conversation-profile-handoff.md for selection, status, redaction, ownership, and DevElation hook details.

Conversation Scene Contracts

BlueFission\SynthetIQ\Scenes\SceneContract validates deterministic scene definitions for authored conversation paths. Scene definitions include states, dialogue prompts, choices, fallback prompts, voice policy, public-safety constraints, and handoff metadata.

See docs/conversation-scenes.md for the full contract shape and package boundaries.

Notes and Constraints

• This library is not a generative model. It predicts and selects from known statements.
• Some skills (weather/news/status) depend on external services or app-specific globals and should be wired explicitly or excluded in lightweight deployments.
• src/Models/LearningModel.php is optional and not yet integrated with SynthetIQ.
• Generated cache and model artifacts belong under models/ and should not be committed.
• Spell correction is lightweight and vocabulary-driven. You can disable it with:

Testing

See tests.md for the full clean-install checklist, focused suites, optional fixture environment variables, and generated artifact policy.

Optional JenSS fixture smoke tests require a local Jenerator autoload path:

Benchmarking

The current benchmark is a local smoke command, not a hard CI budget gate.

License

MIT