aatoolkit

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 0 Imported by: 0

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.

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).
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 extract provides the wire contract and interface for an extraction sidecar.
Package extract provides the wire contract and interface for an extraction sidecar.
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 (design/aa-server-status.md §6.1 stage 3, §7.1) in the two forms a server may declare it: a single GET request whose 2xx response is the authoritative "serving" signal, or a command whose exit status of 0 is.
Package health implements the mandatory health gate for aa-server-status servers (design/aa-server-status.md §6.1 stage 3, §7.1) in the two forms a server may declare it: a single GET request whose 2xx response is the authoritative "serving" signal, or a command whose exit status of 0 is.
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.
realtime
Package realtime speaks the subset of the OpenAI-Realtime websocket protocol an external voice backend needs: a session handshake, inbound audio append, and the server events that carry audio, speech boundaries, and transcripts.
Package realtime speaks the subset of the OpenAI-Realtime websocket protocol an external voice backend needs: a session handshake, inbound audio append, and the server events that carry audio, speech boundaries, and transcripts.
twilio/smsfake
Package smsfake is the fake-Twilio SMS round trip: it builds and signs the inbound-SMS webhook a real Twilio account would post to a server, and it stands in for the Twilio Messages REST API so the server's outbound reply can be captured and asserted on without a real account.
Package smsfake is the fake-Twilio SMS round trip: it builds and signs the inbound-SMS webhook a real Twilio account would post to a server, and it stands in for the Twilio Messages REST API so the server's outbound reply can be captured and asserted on without a real account.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL