Download the PHP package asterixcapri/neuron-interaction without Composer

Neuron Interaction

Neuron Interaction is a PHP library providing sessions, commands, selections and user preferences for applications built with Neuron AI.

Use it to save and resume conversations, offer reusable commands, ask users to choose an option, recall previous inputs and persist their preferences. The same modules work with a terminal, web backend or another delivery mechanism. Each Host Application supplies an Adapter for its UI and response model, and controls presentation, Agent execution and response streaming.

Installation

Requires PHP 8.4.1+. The 0.8.x branch supports Neuron AI 3.

Run this command in your application's directory:

Composer also installs Neuron AI as a required dependency. If you install Neuron TUI, Neuron Interaction is already included as its dependency.

What it provides

• SessionStore persists Neuron AI chat Histories and make conversations discoverable, resumable and replaceable without discarding earlier ones.
• Input history records original submissions across Sessions and optionally provides shell-style recall navigation with independent cursor state per UI.
• Commands provide presentation-independent dispatch, admission and completion, together with reusable /clear, /resume, /help and /exit behavior.
• Selections describe choices as serializable values, labels and descriptions, so multi-step interactions can cross backend request boundaries.
• Storage offers in-memory and JSON-file implementations behind a small interface that applications can replace with their own persistence.

Design strengths

• Presentation independence. Commands express interaction effects through an Adapter instead of printing to a terminal or returning a fixed HTTP shape.
• Explicit application ownership. The Host Application controls the active Agent, turn execution, authorization, scheduling, streaming and lifecycle.
• Composable modules. SessionStore, Commands, Input history and Storage can be adopted together or independently; no application facade is required.
• Native Neuron AI integration. Persisted Sessions expose Neuron AI's own ChatHistoryInterface, so they can be installed directly on an Agent.
• Request-safe workflows. Selection state is carried as data and resumed by a later Command invocation; an Adapter does not need to survive between requests.
• Replaceable boundaries. Both presentation and persistence sit behind focused interfaces, keeping framework and infrastructure choices outside the shared interaction model.

SessionStore and Storage

Host Applications explicitly install a History from create() or read($key) on the Agent when they want that conversation managed by this SessionStore. SessionStore does not import arbitrary Agent Histories or automatically select the latest conversation. Only Histories managed through this Store appear in its listing, subject to the existing title rules.

Use InMemoryStorage for transient state, or implement StorageInterface for application-specific persistence. Storage holds namespaced JSON documents identified by logical keys. It preserves string metadata together with data; StoredDocument::size() reports the JSON size of its data.

SessionStore::create() creates a distinct empty History. SessionStore::summaries() returns Sessions with user-authored text, ordered by most recent use and then key. Titles preserve the first non-blank user-authored textual content without terminal placeholders, escaping or truncation. SessionStore::read($key) reopens its stored History or returns null for absent or other-user keys. SessionStore::delete($key) deletes only the current user’s Session and is a no-op when absent. Sessions expose getKey() and getUserId(); History updates persist automatically. Supply a stable local or authenticated identity when constructing the Store. Ownerless documents are never assigned implicitly.

Application metadata use camelCase names and string values. Pass initial values when creating a Session, then update individual values; these changes persist immediately and preserve its messages. Application fields named userId or lastUsedAt remain ordinary metadata and cannot change ownership or ordering.

Multiple filters are combined with AND using exact string equality. Missing keys do not match; extra metadata are ignored. Results always belong to the Store's user and retain the same title, empty-conversation and ordering rules. Metadata edits preserve the last History-use time; adding or clearing messages updates it and retains application metadata.

Input history

Adapters record original submissions, including their Command invocation syntax, and exclude prompts generated by Commands. Blank inputs are ignored; only consecutive exact duplicates collapse. Each read and append uses the current Storage sequence, so existing instances see one another's submissions. Simultaneous writes are not coordinated by this module; Adapters must serialize them when sharing Storage across concurrent writers.

The same InputHistory instance optionally provides recall navigation:

Each instance keeps its own position and draft in memory; only the input sequence is persisted and shared. Adapters own keyboard handling and decide when to leave navigation, such as on editing or submitting input. A web frontend can use only entries() and navigate locally in JavaScript, without a backend call for each arrow key.

No Neuron TUI dependency, legacy reader, format fallback or automatic migration is supplied. Existing legacy files are left untouched.

Commands

Commands let users perform actions such as starting a new conversation or reopening a saved one. The library includes:

Choose which Commands your application offers and mount them explicitly:

The Adapter decides how to display messages, offer choices and end the interaction. A terminal Adapter can update the screen; a backend Adapter can return response data. The Commands work with either.

To reopen a known Session, pass its key as the arguments:

Write a Command

A Command provides its name, a short description and the action to perform:

See the Command and Adapter reference for custom Adapters, mounting, execution outcomes and error handling.

Backend examples

These examples use BackendAdapter to collect Command messages and choices into response data. They run locally without an HTTP server, API credentials or model requests.

Each backend example is self-contained and demonstrates one flow:

Run any file after installing development dependencies:

In resume-selection.php, the first request offers saved conversations. The second simulates the user's choice and reopens that conversation with a fresh Agent and Adapter. The example provides its own sample data in memory.

Configuration in Commands

Commands access the Host Application's configuration store through CommandAdapterInterface::configurationStore(), just as they access conversations through sessionStore(). Adapters must provide the same ConfigurationStore instance throughout the interaction, including selection continuations.

Read individual preferences with $store->read('model', 'default-model'), write with $store->write('model', 'chosen-model'), remove with $store->delete('model'), and inspect original values with $store->entries(). The fallback selects the read type: read('retries', 3) accepts integers, while read('model', 'default-model') accepts non-empty strings. Missing or incompatible values return the fallback; reads without one return a non-empty string or null. Writes persist through the supplied Storage immediately. See ConfigurationStore for value validation, user isolation and compatibility: old named configurations remain untouched and are not automatically imported.

Development

Commands during Agent work

ConcurrentCommandInterface extends CommandInterface without adding methods. Implement it when a Command can execute while the Agent is working without interfering with state used by that work. Help and Leave implement this marker. Adapters decide whether to admit these Commands and still provide the ordinary CommandAdapterInterface; the marker does not enforce restricted controls.