Skip to content

development-guide.md

Latest commit

 

History

History
138 lines (116 loc) · 5.54 KB

development-guide.md

File metadata and controls

138 lines (116 loc) · 5.54 KB

Development Guide

This document covers how to set up, build, test, and contribute to Brain.

Check the Glossary for key terms such as Layer, System, Resource, Service, et cetera.

Prerequisites

  • Python 3.13
  • Docker and Docker Compose (for Postgres, Qdrant, and other services)
  • Ollama (recommended for embedding, optional for inference)
  • Obsidian with the Local REST API plugin

Environment Setup

  1. Clone the repository and install Python dependencies:

    pip install -r requirements.txt

  2. Start infrastructure services:

    cp .env.sample .env
make up

    This runs Docker Compose, which starts Postgres, Qdrant, signal-api, and any other containerized services defined in docker-compose.yaml.

  3. If migrating existing signal-cli account state, copy it into ./data/signal-cli:

    mkdir -p ./data/signal-cli
cp -R /path/to/existing/signal-cli/. ./data/signal-cli/

    Copy, do not move, until webhook ingress and account state are verified in this deployment.

  4. Copy and edit the configuration sample:

    mkdir -p ~/.config/brain
cp config/core.yaml.sample ~/.config/brain/core.yaml
cp config/resources.yaml.sample ~/.config/brain/resources.yaml
cp config/actors.yaml.sample ~/.config/brain/actors.yaml

    The samples include defaults for Core HTTP socket settings, resource endpoints, and actor connection settings; override them as needed for your environment. See the Configuration Reference for all available keys.

  5. Start Brain Core. It bootstraps schemas and runs migrations automatically during startup.

deprecated/ is not part of this runtime path and remains reference-only.

Make Targets

Target Description
make all Full pipeline: deps, clean, unit + integration tests, docs
make deps Install Python dependencies from requirements.txt
make clean Remove generated code and Python cache files
make check Run linting and format checks (ruff)
make format Auto-format code (ruff)
make test Run lint checks, then pytest across tests/, resources/, services/, and actors/
make docs Regenerate glossary, service-api docs, and diagrams
make outline Print the top-level project directory outline
make up Start Docker Compose services (detached)
make down Stop Docker Compose services

Running Tests

make test             # unit
make test integration # unit & integration

This runs make check first, then executes pytest.

Tests are discovered in four locations:

  • tests/ -- shared and cross-cutting tests
  • actors/ -- Actor-level tests in actors/<actor>/tests
  • services/ -- Service-level tests in services/<system>/<service>/tests/
  • resources/ -- Resource-level tests in resources/<kind>/<resource>/tests

Adding a New Service

  1. Create services/<system>/<service>/ with an __init__.py.
  2. Add a component.py exporting a ServiceManifest via register_component() (see Component Design).
  3. Implement the Public API in service.py.
  4. For database-backed Services:
    • Schema name is derived from the ComponentId.
    • Use shared ULID PK helpers targeting <schema>.ulid_bin.
    • Create an Alembic environment under migrations/.
    • See the Shared Infrastructure section of Boundaries & Responsibilities.
    • Keep runtime settings and typed service contracts aligned with the Pydantic usage rules in Conventions.
  5. Start Brain Core to bootstrap your schema and run migrations.
  6. Add tests in services/<system>/<service>/tests/.

Adding a New Resource

  1. Create resources/<kind>/<resource>/ (kind is substrates/ or adapters/).
  2. Add a component.py exporting a ResourceManifest via register_component().
  3. Set owner_service_id to the L1 Service that owns this Resource.
  4. See Component Design for full registration details.

Contributing Documentation

When writing or editing documentation, follow the formatting rules in Documentation Conventions. For per-component README files, follow Component README Guide.

Linting and Formatting

Brain uses Ruff for both linting and formatting. Configuration is in ruff.toml.

make check    # lint + format check
make format   # auto-format

Database Bootstrapping

Brain Core bootstraps schemas, creates the ulid_bin domain, and runs Alembic migrations in System-order (State -> Action -> Control) during startup. See the Shared Infrastructure section of Boundaries & Responsibilities for details.

End of Development Guide