README
¶
aatoolkit
An open toolkit for building conversational AI assistants.
aatoolkit provides the reusable mechanism for an assistant that talks to people
over the phone and remembers what it learns:
- Telephony — Twilio media-stream handling, session management.
- Speech — speech-to-text and voice-activity detection.
- LLM transport — an OpenAI-compatible driver with tiered models and streaming.
- Dynamic policy loading — load and hot-reload assistant behavior written in Go, at runtime, so the policy can evolve without rebuilding the engine.
- Fact-database toolkit — extract facts from conversation and store them in a graph (Apache AGE / openCypher) with a vector store alongside.
It is mechanism, not a finished assistant. The particular behavior, identity, and
policy of a specific assistant live in a separate private repository that depends on
this module. Dependencies flow one way: private → aatoolkit, never the reverse.
Status
Early. The reusable packages are being extracted from their original monorepo; the
public API will change until it settles. See design/ for the architecture.
License
MIT — see LICENSE.
Documentation
¶
Overview ¶
Package aatoolkit is an open, reusable toolkit for building conversational AI assistants: telephony (Twilio media streams), speech-to-text and voice-activity detection, LLM transport, a dynamic-Go policy loader for hot-reloadable behavior, and a fact-database toolkit for extracting and storing knowledge in a graph.
It provides mechanism, not a finished assistant. The particular behavior, identity, and policy of any given assistant live in a separate, private repository that depends on this module — never the reverse.
Extraction of the reusable packages from their original monorepo is in progress; see design/ for the architecture and the split plan.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
aa-server-status
command
RealEngine is the reconciliation engine wiring launchers (internal/lifecycle), teardown (internal/lifecycle), observation (internal/observe), and health (internal/health) into the fleet verbs (design/aa-server-status.md §2, §3, §6.3, §6.5).
|
RealEngine is the reconciliation engine wiring launchers (internal/lifecycle), teardown (internal/lifecycle), observation (internal/observe), and health (internal/health) into the fleet verbs (design/aa-server-status.md §2, §3, §6.3, §6.5). |
|
ftest
command
Command ftest probes how well a local LLM extracts storable facts from everyday conversation, against a caller-supplied ontology (predicate vocabulary + entity types + system prompt).
|
Command ftest probes how well a local LLM extracts storable facts from everyday conversation, against a caller-supplied ontology (predicate vocabulary + entity types + system prompt). |
|
probeset
command
|
|
|
twilio-cli
command
|
|
|
twprobe
command
|
|
|
wsecho
command
Command wsecho is a throwaway WebSocket echo server for local testing of twilio-cli.
|
Command wsecho is a throwaway WebSocket echo server for local testing of twilio-cli. |
|
Package config loads and validates aa-server-status's TOML configuration: a committed base file deep-merged with a gitignored local overlay for secrets.
|
Package config loads and validates aa-server-status's TOML configuration: a committed base file deep-merged with a gitignored local overlay for secrets. |
|
Package driver is the compiled engine an agent runs on: the LLM HTTP client (Host, a host.Host implementation), TTS synthesis + playback, the serial speech queue, and health/Twilio HTTP servers.
|
Package driver is the compiled engine an agent runs on: the LLM HTTP client (Host, a host.Host implementation), TTS synthesis + playback, the serial speech queue, and health/Twilio HTTP servers. |
|
Package ftest is a probe harness for measuring how well the local LLM extracts storable facts from everyday conversation.
|
Package ftest is a probe harness for measuring how well the local LLM extracts storable facts from everyday conversation. |
|
Package host defines the surface that an interpreted chat policy needs from its compiled driver.
|
Package host defines the surface that an interpreted chat policy needs from its compiled driver. |
|
internal
|
|
|
health
Package health implements the mandatory health gate for aa-server-status servers: a single GET request whose 2xx response is the sole authoritative "serving" signal (design/aa-server-status.md §6.1 stage 3, §7.1).
|
Package health implements the mandatory health gate for aa-server-status servers: a single GET request whose 2xx response is the sole authoritative "serving" signal (design/aa-server-status.md §6.1 stage 3, §7.1). |
|
lifecycle
Package lifecycle implements the common child-launch machinery shared by every server type — process-group isolation, per-server environment overlay, and log-file management — plus the two launchers whose command shapes need no further logic (mlx, exec).
|
Package lifecycle implements the common child-launch machinery shared by every server type — process-group isolation, per-server environment overlay, and log-file management — plus the two launchers whose command shapes need no further logic (mlx, exec). |
|
observe
Package observe is aa-server-status's observation layer: it answers "what is actually running" without ever killing or launching anything.
|
Package observe is aa-server-status's observation layer: it answers "what is actually running" without ever killing or launching anything. |
|
Package interp is the generic mechanism for loading Go "policy" source at runtime: read a directory of .go files, compile them as a named package under a fresh yaegi interpreter, inject a set of host symbols the policy may import, and evaluate an expression (typically a function symbol) that the caller type-asserts and calls.
|
Package interp is the generic mechanism for loading Go "policy" source at runtime: read a directory of .go files, compile them as a named package under a fresh yaegi interpreter, inject a set of host symbols the policy may import, and evaluate an expression (typically a function symbol) that the caller type-asserts and calls. |
|
assets
Package assets embeds vendored binary model assets so the telephony package never needs a runtime file read to load them.
|
Package assets embeds vendored binary model assets so the telephony package never needs a runtime file read to load them. |
Click to show internal directories.
Click to hide internal directories.