abstractframework

AbstractFramework

Write once. Generate everything.

A modular, open-source ecosystem for building durable, observable, multimodal AI systems. Text, voice, image, video, music — one unified interface, any provider, any model, local or cloud.

AbstractFramework is an ecosystem of composable packages for building AI systems that work in operational reality:

• Durable by default: workflows pause and resume safely (survive crashes and restarts)
• Observable: an append-only ledger so any UI can reconstruct state by replaying history
• Controlled actions: explicit boundaries for tool execution, approvals, and evidence
• Multimodal: capability plugins (voice, vision, music) that stay out of your way until you need them

Think of it as an agentic OS: durable runs + replay-first observability + multimodal capabilities — write once, run across providers and deployment modes.

Prerequisites: none for the one-line install below (it provisions Python and, optionally, Node.js). For a manual install: Python 3.10–3.13, Node.js 18+ for browser UIs, and an LLM backend (Ollama, LM Studio, vLLM, or a cloud API key).

---

Install

• Mac, no Terminal: download and double-click AbstractFramework-Installer.pkg. The package is not signed with an Apple Developer ID, so the first time macOS blocks it: open System Settings > Privacy & Security, click Open Anyway next to the installer's name and confirm. A Terminal window then shows each step; press Return at its one question.

• macOS / Linux, one line:

  curl -LsSf https://abstractframework.ai/install.sh | sh
  

• Windows 10 22H2+ / 11 (PowerShell):

  powershell -ExecutionPolicy ByPass -c "irm https://abstractframework.ai/install.ps1 | iex"
  

To upgrade, run the same line again (on a Mac, double-clicking Install AbstractFramework.command again does the same), or, on macOS and Linux, press Update in the web console, the terminal console or the menu-bar icon: each runs the same installer, which installs the latest AbstractFramework release, keeps your settings, options and data, and lists what changed. Coming from 0.6.1 or earlier, re-run the line once: it reads your earlier options from what is installed (or repeat them once), and the Update button of gateway 0.7.1 cannot upgrade. Gateway only, apps, and version checks: Upgrade.

On Linux or Windows with an NVIDIA GPU (nvidia-smi works), the installer picks the gpu profile: PyTorch and llama.cpp on CUDA, Whisper on the GPU, Diffusers image generation. On Linux it needs NVIDIA driver 580 or newer; measured install and per-capability timings on a Quadro RTX 5000 with Ubuntu 26.04 are in GPU on Linux. The Windows gpu install is implemented but not yet validated on real NVIDIA hardware. See GPU on Linux and GPU on Windows.

The installer sets up the gateway in your user account (no admin password, no system Python), with local voice (Supertonic text-to-speech and Whisper speech-to-text), asks whether to start it at login (Enter = yes; an unattended install leaves it off and says how to turn it on), starts it on 127.0.0.1:8080, and opens its web console in your browser already signed in. A first-run guide then sets up a local engine (Ollama, LM Studio, MLX, llama.cpp), downloads a model that fits your machine, and lists the apps; the gateway serves them on its own address at /apps/<app>/. The Setup button at the bottom of the console's sidebar runs the guide again, keeping your choices unless you replace them. The installer also builds the terminal console, abstractgateway-console, which runs the same guide on a server without a browser and offers itself at the end of an install over SSH (Headless or remote machine).

Every failure says what to do next; running the installer again repairs the install in place. To remove it, double-click Uninstall AbstractFramework.command (in ~/Library/Application Support/AbstractFramework/Installer after a package install), or run curl -LsSf https://abstractframework.ai/uninstall.sh | sh. Step by step, the failure table, options (--with-apps, --with-ollama, --print, …): Install. Something not working: Troubleshooting.

Already have Python? Either entry point works the same way: start it, then open the link it prints.

pip install abstractcore && abstractcore serve        # http://127.0.0.1:8000/console#claim=…
pip install abstractgateway && abstractgateway serve  # http://127.0.0.1:8080/console#claim=…

Both consoles let you browse models that fit this machine, download and delete them (Models), and detect and install local engines (Engines in the Core console, Providers in the gateway console); every action also shows its command-line equivalent (abstractcore models …, abstractcore engines …, abstractgateway models …).

---

Two entrypoints

Start lightweight with just the LLM library, or go all-in with a production gateway. Both paths lead to the same ecosystem.

1) AbstractCore — LLM SDK + OpenAI-compatible /v1 server

Start here if you need a lightweight LLM library for scripts, notebooks, or existing applications. No infrastructure required — just pip install and call. Add multimodal capabilities with plugins as you grow.

• 9+ providers with identical API (local + cloud)
• Universal tool calling, structured output, streaming
• Media handling (images, PDFs, audio, video)
• OpenAI-compatible HTTP server mode (/v1)
• Multimodal via capability plugins (Voice, Vision, Music)

pip install abstractcore              # light: every remote provider (OpenAI, Anthropic, OpenRouter, Ollama, LM Studio, ...)
pip install "abstractcore[apple]"     # + the local engines of an Apple silicon Mac (MLX, voice, image, video, music)
pip install "abstractcore[gpu]"       # + the local engines of an NVIDIA or AMD machine (vLLM, voice, image, video, music)

from abstractcore import create_llm

llm = create_llm("ollama", model="qwen3:4b-instruct")
resp = llm.generate("Explain durable execution in 3 bullets.")
print(resp.content)

abstractcore serve starts the /v1 server on 127.0.0.1:8000 and prints a one-time link to its web console (Overview, Models, Engines, Providers). The same Models and Engines screens are available from the command line (abstractcore models catalog|list|download|delete, abstractcore engines status|install) and in the terminal console (cargo install abstractcore-console).

AbstractCore gives you one interface for provider switching, tools, structured output, and media — as a Python SDK or via /v1 for any OpenAI-compatible client.

2) AbstractGateway — durable run control plane (HTTP/SSE APIs)

Start here if you're building persistent AI applications — agents that run for hours, workflows that survive crashes, scheduled tasks. The gateway is your AI control plane: durable runs with ledger replay/streaming and thin clients that can attach/detach across devices.

• Durable execution that survives crashes and restarts
• Append-only ledger (replay-first) for auditability
• Automations: a workflow that runs on a fixed interval, when an email arrives, or on demand, kept as a readable conversation (Automations)
• Email for each user: your email address receives sign-in codes and notifications; connect your own mailbox (IMAP, Google or Microsoft) to get failed jobs, approvals and automation results by email, and let your agents use email tools when you switch them on (Email integration)
• Multi-client: terminal, browser, tray, Telegram, email
• Start on one device, continue on another: the web console and every browser app work on phones, tablets and any window size (Phones and tablets)

pip install abstractgateway
abstractgateway serve

With no auth configured, abstractgateway serve binds 127.0.0.1:8080, enables user auth, creates default/admin in the per-user data folder, and prints a one-time sign-in link (http://127.0.0.1:8080/console#claim=…, valid 10 minutes, this machine only). Open it to reach the web console and its first-run guide. abstractgateway claim mints a new link; abstractgateway service enable (or the console's Start at login switch) starts the gateway at login.

Browser apps on http://localhost:* and http://127.0.0.1:* may always call it. To choose another data folder or allow another browser origin:

abstractgateway serve --data-dir "$PWD/runtime/gateway"
abstractgateway network set --allowed-origins https://ui.example.com

To serve your own workflow bundles instead of the shipped ones, start the gateway with ABSTRACTGATEWAY_FLOWS_DIR pointing at your bundle folder.

Out of the box this serves a ready set of workflows — a verify-gated coding agent, deep-research, and co-scientist among them. See shipped workflows.

The admin user token is kept in <data dir>/auth/bootstrap-admin-token; use it to sign in to AbstractFlow, AbstractCode Web or AbstractObserver, or to the console without a claim link. ABSTRACTGATEWAY_AUTH_TOKEN remains a legacy server/operator bearer token; it is not a browser sign-in token.

Monitor runs from a browser, or from a terminal with the gateway console. The console's Apps page installs, opens and updates the browser apps and the Assistant (Update to x.y.z when a newer release exists); the browser apps are served by the gateway at /apps/<app>/ (http://127.0.0.1:8080/apps/observer/), so one address (and one SSH tunnel) reaches them all:

npx @abstractframework/observer --gateway-url http://127.0.0.1:8080   # or run one on its own

cargo install abstractgateway-console   # Rust 1.87+; the installer builds it for you
abstractgateway console                 # opens it signed in (gateway 0.15.6+); or by hand:
abstractgateway-console --gateway-url http://127.0.0.1:8080 --token <admin token>   # <data dir>/auth/bootstrap-admin-token
abstractgateway update --check          # what the next upgrade changes; `abstractgateway update` runs it (gateway 0.15.6+)

Container images are published for the gateway and the AbstractCore server: ghcr.io/lpalbou/abstractgateway:0.15.11 and ghcr.io/lpalbou/abstractcore-server:2.26.3.

For artifact and runtime-resource investigation, see Runtime artifacts and retrieval.

Agent sessions on the gateway

Every client (AbstractCode in the terminal and the browser, AbstractAssistant, your own app) chats with agents through the same gateway rules:

• One default agent workflow. The gateway decides which workflow answers each agent interface (agents.default_workflow.<interface>; the shipped basic-agent for AbstractCode until you choose another). Clients list Gateway default first and follow a change at the next turn.
• A workspace you can see, with built-in protection. An agent works in its conversation's private folder on the gateway's computer; AbstractCode's Files tab and /files show its absolute path and preview its files. The admin chooses a posture (Deny everything, allow listed workspaces or Allow everything, refuse listed workspaces), one Shared workspace (always Read & write) and workspaces that are Read-only, Read & write or Refused; each account can only narrow them. Credential folders (~/.ssh, ~/.aws, …) and the gateway's data folder are denied to every run.
• Curated skills. The skill shelf that ships with abstractskill is copied into the gateway's data folder at each start, without overwriting your edits (skills.shelf points elsewhere).
• Live replies. Watch answers as the model writes them: the gateway's agents.streaming_default plus a Stream replies choice in each client.
• The Assistant, signed in for you. Open in the gateway console starts the desktop Assistant already signed in; no token to type.
• About everywhere. Every app's About screen shows the framework identity and the versions the connected gateway runs (GET /api/gateway/about).
• Clean model eject. Ejecting a model frees it from the whole gateway process (MLX, GGUF, transformers, embeddings); the console shows the memory the process holds and how it was measured.

Each setting is available in the web console, the terminal console and abstractgateway config. See Agent sessions.

---

Author once, run everywhere (AbstractFlow)

AbstractFlow lets you author complex agentic orchestration as portable .flow bundles:

1. Open the Flow Editor (the console's Apps page, or npx @abstractframework/flow --gateway-url <url>)
2. Build a workflow: LLM steps, tool steps, branching, loops, subflows
3. Export a .flow bundle into your own bundle directory and point ABSTRACTGATEWAY_FLOWS_DIR at it (or publish it through the Gateway API)
4. Run it from any gateway-backed client (Observer, AbstractAssistant, Code Web UI, your app)

AbstractAgent provides ready-made agent patterns (ReAct, CodeAct, MemAct) that can be used inside flows or standalone. The workflows Gateway ships with are authored the same way — their editable sources are documented in shipped workflow sources.

---

Monitor and schedule with AbstractObserver

• Observe: replay the full ledger of any run, or watch one live over SSE
• Control: cancel, resume, or inspect runs from the browser
• Automate: create and manage automations (Launch → Automate, the Automations page); they run on the gateway and survive restarts. See Automations

---

Package map

The ecosystem, grouped by layer. Each name links to the package's repository.

Foundation

Durable execution

Control plane

Multimodal capabilities

Apps and clients

The gateway's web console and the five browser apps (Code Web UI, Flow Editor, Observer, Entity, Continuum) adapt to phones, tablets and windows of any size: drawers below 1024 px, bottom-sheet dialogs and touch-sized controls on phones.

Shared libraries

---

Install the pinned ecosystem profile

Light / Apple / GPU profiles

Choose how the framework runs based on your hardware and constraints. All profiles keep the same interfaces; they mainly change which local inference stacks are available.

Light (default) — endpoint-only inference (cloud APIs or local OpenAI-compatible servers), no in-process ML engine stacks:

pip install abstractframework

Apple — native Apple Silicon local stacks (MLX/Metal) in addition to endpoint providers:

pip install "abstractframework[apple]"

GPU — native GPU local stacks (CUDA/ROCm) in addition to endpoint providers:

pip install "abstractframework[gpu]"

Release matrix (abstractframework 0.11.0)

abstractframework pins every Python package with ==, so one version of the meta-package always installs the same stack. The browser apps and Rust tools are distributed through npm and crates.io; the versions below are the ones released and tested together.

abstract3d (pinned above) comes with AbstractCore in every profile. The optional add-on that is not part of any profile installs separately: pip install abstractcamera (0.2.1). abstractskill (pinned above) comes with the gateway, which carries its curated skill shelf; install it on its own with pip install abstractskill.

See docs/install.md for the full install chooser, uv/venv guidance, abstractframework doctor, and the generated installer manifest contract.

---

Documentation

---

Developer setup (from source)

Clone all sibling repos and build everything in editable mode:

./scripts/clone.sh           # clone every sibling repository next to this one
./scripts/deps.sh            # dependency tiers: what builds and installs first, and why
source ./scripts/build.sh    # Python (editable, into .venv), npm and Rust builds, tier by tier

Keep the whole workspace in sync with ./scripts/status.sh (git overview per tier; --registry compares local versions with PyPI, npm and crates.io), ./scripts/pull.sh, ./scripts/commit.sh and ./scripts/push.sh (a dry run until you add --yes). See docs/workspace-scripts.md for every script and option.

Then configure providers and models in a console (abstractcore serve or abstractgateway serve, then open the printed link), or from the terminal:

abstractcore --config    # interactive configuration wizard
abstractcore --install   # check every subsystem and download missing models and dependencies

---

License

MIT. See LICENSE. Credits: ACKNOWLEDGEMENTS.md. Community expectations: CODE_OF_CONDUCT.md.