Metadata-Version: 2.4
Name: abstractassistant
Version: 0.17.0
Summary: A gateway-native macOS menu-bar assistant for AbstractFramework: a compact palette, hands-free voice conversations, automations and a small CLI over AbstractGateway
Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lpalbou/abstractassistant
Project-URL: Repository, https://github.com/lpalbou/abstractassistant
Project-URL: Issues, https://github.com/lpalbou/abstractassistant/issues
Project-URL: Changelog, https://github.com/lpalbou/abstractassistant/blob/main/CHANGELOG.md
Keywords: ai,llm,macos,system-tray,assistant,voice,abstractgateway,abstractframework
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Desktop Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: abstractruntime>=0.15.0
Requires-Dist: abstractvoice[audio-io]>=0.19.5
Requires-Dist: abstractcore>=2.16.0
Requires-Dist: pyobjc-framework-Cocoa>=10.0; sys_platform == "darwin"
Requires-Dist: Pillow>=10.0.0
Requires-Dist: PyQt5>=5.15.0
Requires-Dist: pynput>=1.7.7
Requires-Dist: pyobjc-framework-ApplicationServices>=10.0; sys_platform == "darwin"
Requires-Dist: markdown-it-py>=4.0.0
Requires-Dist: pygments>=2.16.0
Requires-Dist: setuptools<81,>=61.0
Provides-Extra: avatar
Requires-Dist: abstractavatar>=0.1.0; extra == "avatar"
Provides-Extra: lite
Provides-Extra: voice
Requires-Dist: abstractvoice[audio-io,stt]>=0.19.5; extra == "voice"
Provides-Extra: apple
Requires-Dist: abstractcore[all-apple]>=2.16.0; extra == "apple"
Requires-Dist: abstractvoice[all-apple]>=0.19.5; extra == "apple"
Provides-Extra: gpu
Requires-Dist: abstractcore[all-gpu]>=2.16.0; extra == "gpu"
Requires-Dist: abstractvoice[all-gpu]>=0.19.5; extra == "gpu"
Provides-Extra: all
Requires-Dist: abstractvoice[audio-io,stt]>=0.19.5; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: pyinstaller>=6.21.0; extra == "dev"
Provides-Extra: macos-app
Requires-Dist: pyinstaller>=6.21.0; extra == "macos-app"
Dynamic: license-file

# AbstractAssistant

AbstractAssistant is a gateway-native desktop assistant for the AbstractFramework ecosystem: a
macOS menu-bar app with a compact palette, a hands-free voice conversation mode, and a small CLI.

The desktop client stays thin. AbstractGateway owns workflow discovery, durable runs, provider
connections, tool execution and policy, workspace policy, and multimodal defaults. The assistant
keeps only local state: your chats, window placement, downloads, and the overrides you choose for
this app.

```text
Tray / Palette / CLI -> AbstractGateway -> AbstractRuntime -> AbstractCore -> Providers
```

## What you get

- A menu-bar palette whose title tells you what the app is doing, with a session switcher fed by
  the gateway (your sessions from every device, optionally every client's) and a live gateway
  connection orb.
- An optional local [AbstractAvatar](https://github.com/lpalbou/AbstractAvatar) portrait in the palette,
  with design and motion controls in [Appearance](docs/settings.md#appearance--window). It follows
  listening, speech, tools, waits and errors; it stays off until you enable it.
- Automations: schedule a conversation to run on the gateway at a fixed UTC interval or when an
  email arrives (with the result emailed to you if you want), read its runs
  as a chat, switch it off or on (**Active**), run it now, edit or archive it, answer the runs that wait for you, discuss a
  result, and get a tray notification only when a result is notable, a run fails or a run waits for
  you. See [docs/automations.md](docs/automations.md).
- What waits for you, everywhere: the app follows your event stream on the gateway, so the attention
  badge beside the session control and the menu-bar badge show the approvals, questions and new
  automation results across every conversation, within seconds. A click on the badge opens exactly
  what it counts. On
  one Mac you get one notification per item: the gateway's tray icon notifies first and the
  Assistant stays silent for what it already showed.
- Live run activity in the transcript: the current step, elapsed time, recent tool calls with
  their arguments and durations, and pause / resume / stop controls.
- Live replies: with **Stream replies** on (the default), the
  answer appears while the model writes it, with its reasoning folded away under **Thinking**;
  the finished answer replaces the live text.
- Tool approvals in a modeless sheet that shows the gateway's risk tier for each call and never
  blocks the palette; "always allow on this Mac" and per-chat trust for low-risk tools.
- Hold the microphone button to talk: release sends the words. A voice conversation mode (⌘⇧V,
  or the microphone's right-click menu): listen, send, speak, listen again — with a live status
  strip. Spoken replies stream from the gateway.
- A Settings window with seven sections: Connection, Models & reasoning (workflow, reasoning
  effort, reply streaming), Voice, Workspace (my default workspaces, this chat), Tools & permissions,
  Appearance & window, About. Every value says whether it is the gateway default or this app's
  override. About is also on the menu-bar icon (**About AbstractAssistant…**).
- Local, persistent overrides for every route the assistant drives (chat, voice, image, video,
  music, sound) that ride each request without touching the gateway's shared defaults.
- Per-answer statistics (tokens, tools, files, duration, model) with clickable detail views.
- One reconstruction of every run: on AbstractGateway 0.17.0 or later the desktop app, `assistant run`
  and the web Assistant (`web/`) render a run from the gateway's replay view (`GET /runs/{id}/view`
  and its stream): status, replies, tool rows and the approval or question wherever it waits come
  from the gateway, so an approval answered on another client closes here too. On an older gateway
  the app folds the run's ledger itself and says so.
- Multi-attachment composer with an image gallery, drag and drop, and artifact previews.
- In your pocket and on your wrist: **AbstractAssistant for iPhone and Apple Watch** is one app
  (0.16.0, pre-release through TestFlight): the iPhone app carries the watch app, each signs in
  on its own and works without the other, and notifications reach you while the app is closed (Apple push, once your gateway
  has a push forwarder). The iPhone has the same conversations, tools and automations, with tab badges for
  what needs you ([phone/iphone/README.md](phone/iphone/README.md)); the watch talks to the same
  gateway by voice around the orb, answers approvals and questions, continues your sessions and runs
  your automations, and your avatar on the watch face shows what needs you
  ([watch/apple/README.md](watch/apple/README.md)).

## What's new

0.17.0 adds the optional desktop activity avatar (the `avatar` extra), automations that open as
the chat with a sectioned editor, tool approvals in words, Off / Ask / Auto tool settings, and the
web Assistant's Avatar conversation view. See the [0.17.0 release notes](CHANGELOG.md#0170---2026-11-02).

## Install

```bash
pip install "abstractassistant[voice]"
```

Add the `avatar` extra (`pip install "abstractassistant[voice,avatar]"`) for the optional activity
avatar in the palette.

The `voice` extra adds local microphone capture (dictation and voice conversations). The base
install covers text chat, spoken replies and gateway-backed media; STT and TTS run on the gateway
either way.

Requirements: Python 3.10+, an AbstractGateway you can reach (0.16.0 or later for the voice
library and the chat-wide tool policy; an older gateway keeps the labeled local grant and refuses
the voice library's requests; 0.19.0 or later for read marks shared across your devices, without
which conversation cards show no unread marks). AbstractCore is installed as a
dependency (its minimum version is set in `pyproject.toml`). macOS is the primary tray target;
Linux and Windows may work but are not packaged to the same standard.

## Quick start

Start a local gateway for development:

```bash
export ABSTRACTGATEWAY_FLOWS_DIR="$PWD/abstractgateway/flows/bundles"
export ABSTRACTGATEWAY_AUTH_TOKEN="your-shared-token"
abstractgateway serve --host 127.0.0.1 --port 8080
```

Launch the tray assistant:

```bash
assistant
```

Run a single terminal turn:

```bash
assistant run --prompt "Search the web for the latest OpenAI news and summarize it with sources."
```

Connection overrides:

```bash
assistant --gateway-url http://127.0.0.1:8080 --gateway-token "$ABSTRACTGATEWAY_AUTH_TOKEN"
```

`--gateway-url` on its own is enough when you have already signed in to that gateway: the app
reuses the sign-in saved in `~/.abstractassistant/gateway_connection.json`.

If the gateway runs the AbstractGateway console, the simplest way to start the assistant is
**Open** on its card there: the console launches the app already signed in as you, and the app
remembers that sign-in for later launches. The console can sign in only an Assistant it launches,
so quit a running Assistant before you click **Open**.

Each turn runs the gateway's default workflow for the assistant (`abstractassistant.agent.v1`).
When the gateway sets none, the app runs its built-in orchestrator, the
`abstractassistant-orchestrator` workflow it publishes to your tenant catalog. You can pick
another assistant workflow in Settings → Workflow; the list holds only the assistant
workflows the gateway says you can run (what your admin made available, plus your own:
`GET /api/gateway/bundles?executable_for=abstractassistant.agent.v1`).

## Defaults and durability

The gateway is the source of truth for the published workflow, provider and model defaults, tool
inventory and approval defaults, workspace policy, run history, waits and artifacts.

The desktop client stores under `~/.abstractassistant/`:

- `preferences.json` — this app's overrides and preferences (model routes, reasoning effort,
  reply streaming, workspace grant, voice options, tool modes, hotkey, window size)
- `gateway_connection.json` — gateway URL and sign-in state
- `session_cache.json`, `sessions/` — a rebuildable cache of the gateway's sessions (local labels,
  cached transcripts, each session's workspace); the sessions themselves live on
  the gateway
- `automations_notified.json` — which automation notifications were already shown; automations
  themselves live on the gateway
- downloads and cached audio

## Documentation

Start with [docs/README.md](docs/README.md).

- [docs/INSTALLATION.md](docs/INSTALLATION.md)
- [docs/getting-started.md](docs/getting-started.md)
- [docs/settings.md](docs/settings.md)
- [docs/voice.md](docs/voice.md)
- [docs/automations.md](docs/automations.md)
- [docs/architecture.md](docs/architecture.md)
- [docs/api.md](docs/api.md)
- [docs/faq.md](docs/faq.md)
- [docs/troubleshooting.md](docs/troubleshooting.md)
- [docs/adr/README.md](docs/adr/README.md)
- [phone/iphone/README.md](phone/iphone/README.md) — the native iPhone app and its [release history](phone/iphone/CHANGELOG.md)
- [watch/apple/README.md](watch/apple/README.md) — the Apple Watch app

## Development

```bash
pip install -e ".[dev]"
QT_QPA_PLATFORM=offscreen python -m pytest tests/basic -q
```

## Project links

- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
- Security: [SECURITY.md](SECURITY.md)
- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Acknowledgments: [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md)
- License: [LICENSE](LICENSE)
