Masterbrain Python Package

Published Python package for the Masterbrain monorepo. It owns the provider-neutral AI core, model provider adapters, FastAPI service, desktop launcher, Python tests, and PyInstaller packaging flow.

The package depends on the sibling airalogy package in source checkouts and uses it to validate and unpack .aira archives for the local protocol/record library.

For platform coverage and packaging limits, see ../../PLATFORM_SUPPORT.md. For PyPI release automation, see ../../RELEASING.md.

Setup

cp .env.example .env
uv sync --dev

packages/masterbrain/.env is the standard location for local runtime configuration.

Run

Start the FastAPI server:

uv run uvicorn masterbrain.fastapi.main:app --reload --host 127.0.0.1 --port 8080

Launch the integrated desktop-style local app after building the frontend in apps/studio:

uv run masterbrain-studio

masterbrain-desktop is kept as a deprecated compatibility alias and will be removed in a future release.

You can bind the app to an existing workspace directory:

uv run masterbrain-studio --workspace /path/to/project

You can also pass an .aira archive path as the launch document. Masterbrain will import it into the local library before opening the UI:

uv run masterbrain-studio /path/to/archive.aira

OpenCode

Code-edit flows require an OpenCode runtime. Either install opencode globally, or vendor it locally:

python3 scripts/vendor_opencode.py

Tests

Run the Python package test suite:

uv run python -m pytest

pytest.ini excludes openai and qwen markers by default.

Packaging

PyPI publishing is handled by the repository-level GitHub Actions release workflow on v* tag pushes.

Build the packaged local bundle with the cross-platform CLI:

uv run masterbrain-build-desktop

Wrapper scripts are also available:

macOS / Linux: ./scripts/build_desktop_bundle.sh
Windows PowerShell: .\scripts\build_desktop_bundle.ps1

This builds the frontend from apps/studio, vendors OpenCode into packages/masterbrain/vendor/, syncs the packaging dependency group, writes the raw PyInstaller bundle to packages/masterbrain/dist/Masterbrain/, and then packages platform release artifacts under packages/masterbrain/dist/release/<platform>/.

macOS: unsigned Masterbrain.app and a versioned .zip
Windows x64: portable directory, portable .zip, and an Inno Setup .iss script; if ISCC.exe is available or passed via --inno-setup-compiler, the installer .exe is also built
Linux: portable directory and a versioned .tar.gz

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

masterbrain-0.9.1.tar.gz (105.1 kB view details)

Uploaded Jul 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

masterbrain-0.9.1-py3-none-any.whl (178.9 kB view details)

Uploaded Jul 20, 2026 Python 3

File details

Details for the file masterbrain-0.9.1.tar.gz.

File metadata

Download URL: masterbrain-0.9.1.tar.gz
Upload date: Jul 20, 2026
Size: 105.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for masterbrain-0.9.1.tar.gz
Algorithm	Hash digest
SHA256	`ec4a96e29e4e5bbd96caafee25871fb30b17c64081fed038de0ec9c819492045`
MD5	`d649d123b0ac3c5f75e7f35e4c3c151b`
BLAKE2b-256	`9aa2fc67d778207ae95438efedb9029747abf1482a01206d5e2b9b9bc116d00c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for masterbrain-0.9.1.tar.gz:

Publisher: release.yml on airalogy/masterbrain

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: masterbrain-0.9.1.tar.gz
- Subject digest: ec4a96e29e4e5bbd96caafee25871fb30b17c64081fed038de0ec9c819492045
- Sigstore transparency entry: 2205498215
- Sigstore integration time: Jul 20, 2026
Source repository:
- Permalink: airalogy/masterbrain@b8d1da7055dbd33f02d4556ba86bcec8b4fe3660
- Branch / Tag: refs/tags/v0.9.1
- Owner: https://github.com/airalogy
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@b8d1da7055dbd33f02d4556ba86bcec8b4fe3660
- Trigger Event: push