Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

feat(cli): added configuration + installation cli

Christianf0b45a2a5c35
diff --git a/.env.example b/.env.example
index 15ac844..e485dcc 100644
--- a/.env.example
+++ b/.env.example
@@ -1,18 +1,37 @@
# LLM Implementation envs
# The following are just examples of the adapter implementation, you can have completely different envs
+LLM_SMALL_PROVIDER="gcp_vertex"
+LLM_LARGE_PROVIDER="azure"
+EMBEDDINGS_PROVIDER="azure"
+AZURE_SMALL_LLM_MODEL="gpt-4o-mini"
AZURE_LARGE_LLM_MODEL="gpt-4o"
-AZURE_LARGE_LLM_API_VERSION="2024-12-01-preview"
-AZURE_LARGE_LLM_ENDPOINT="https://yourproject.openai.azure.com"
+AZURE_LLM_API_VERSION="2024-12-01-preview"
+AZURE_LLM_ENDPOINT="https://yourproject.openai.azure.com"
AZURE_LLM_SUBSCRIPTION_KEY="xyz"
-GCP_EXTRA_SMALL_LLM_MODEL="gemini-2.5-flash-lite"
-GCP_SMALL_LLM_MODEL="gemini-2.5-flash"
+GCP_EXTRA_SMALL_LLM_MODEL="gemini-3-flash-preview"
+GCP_SMALL_LLM_MODEL="gemini-3-flash-preview"
+GCP_LARGE_LLM_MODEL="gemini-3-flash-preview"
+GCP_EMBEDDING_MODEL="text-embedding-005"
GCP_PROJECT_ID="your-project-id"
GCP_CREDENTIALS_PATH=".path-to-credentials-file.json"
+BEDROCK_REGION="us-east-1"
+BEDROCK_ACCESS_KEY_ID="your-access-key-id"
+BEDROCK_SECRET_ACCESS_KEY="your-secret-access-key"
+BEDROCK_SESSION_TOKEN=""
+BEDROCK_SMALL_LLM_MODEL="us.anthropic.claude-3-5-haiku-20241022-v1:0"
+BEDROCK_LARGE_LLM_MODEL="us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+BEDROCK_EMBEDDING_MODEL="amazon.titan-embed-text-v2:0"
+OPENAI_API_KEY="sk-..."
+OPENAI_BASE_URL=""
+OPENAI_SMALL_LLM_MODEL="gpt-4o-mini"
+OPENAI_LARGE_LLM_MODEL="gpt-4o"
+OPENAI_EMBEDDING_MODEL="text-embedding-3-large"
# Embedding envs
# The following are just examples of the adapter implementation, you can have completely different envs
AZURE_EMBEDDING_FULL_ENDPOINT="https://yourproject.openai.azure.com/openai/deployments/text-embedding-3-large/embeddings?api-version=2023-05-15"
AZURE_EMBEDDING_KEY="xyz"
+AZURE_EMBEDDING_MODEL="text-embedding-3-large"
EMBEDDINGS_SMALL_MODEL="paraphrase-multilingual-MiniLM-L12-v2"
EMBEDDINGS_LOCAL_MODEL="intfloat/e5-small"
EMBEDDING_NODES_DIMENSION=3072
@@ -49,12 +68,26 @@ NEO4J_PASSWORD="your_password"
MILVUS_HOST="localhost"
MILVUS_PORT=19530
-# DataDB envs
+# PostgreSQL envs
+# Used for data / vector / graph storage when DATA_DB, VECTOR_DB, or GRAPH_DB
+# point at postgresql / pgvector / networkx.
+# Each brain owns its own Postgres database (brain_<sanitized_id>).
+# POSTGRES_SYSTEM_DATABASE holds the brains registry (data_brains table).
+# POSTGRES_MAINTENANCE_DATABASE is used only for CREATE DATABASE statements.
+POSTGRES_HOST="localhost"
+POSTGRES_PORT=5432
+POSTGRES_USERNAME="postgres"
+POSTGRES_PASSWORD="password"
+POSTGRES_SYSTEM_DATABASE="brainapi"
+POSTGRES_MAINTENANCE_DATABASE="postgres"
+
+# DataDB envs (Mongo alternative to PostgreSQL data layer)
# The following are just examples of the adapter implementation, you can have completely different envs
MONGO_HOST="localhost"
MONGO_PORT=27017
MONGO_USERNAME="root"
MONGO_PASSWORD="password"
+MONGO_SYSTEM_DATABASE="system"
# Auth
# Used to handle authentication
@@ -68,7 +101,7 @@ DEFAULT_BRAIN_FALLBACK="true"
# GCP
# Used on the oss project for the small LLM but can be changed to any other model
-GCP_EXTRA_SMALL_LLM_MODEL="gemini-2.5-flash-lite"
+GCP_EXTRA_SMALL_LLM_MODEL="gemini-3-flash-preview"
GCP_SMALL_LLM_MODEL="gemini-3-flash-preview"
GCP_PROJECT_ID="your-project-id"
GCP_CREDENTIALS_PATH=".path-to-credentials-file.json"
@@ -107,6 +140,9 @@ MODELS_MODE="remote"
OCR_MODE="docparser"
AGENTIC_ARCHITECTURE="custom"
RUN_GRAPH_CONSOLIDATOR="true"
+GRAPH_DB="networkx"
+DATA_DB="postgresql"
+VECTOR_DB="postgresql"
# Ollama
# Used to configure the ollama models
diff --git a/.gitignore b/.gitignore
index 3f828dc..b3b0200 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,4 +20,9 @@ mcp-stdio-http-bridge/dist/
plugins/**
docs/**
-.git
\ No newline at end of file
+.git
+
+tui/node_modules
+tui/dist
+.cursor
+tui/embedded
\ No newline at end of file
diff --git a/Makefile b/Makefile
index c3fd954..5c67917 100644
--- a/Makefile
+++ b/Makefile
@@ -169,4 +169,16 @@ v-minor:
poetry version minor
v-major:
- poetry version major
\ No newline at end of file
+ poetry version major
+
+install-base:
+ poetry install
+
+install-extras:
+ poetry run python scripts/install_extras.py
+
+install-extras-all:
+ poetry run python scripts/install_extras.py --all
+
+check-extras:
+ poetry run python scripts/install_extras.py --check
\ No newline at end of file
diff --git a/README.md b/README.md
index 6bbafc9..fe248cb 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,29 @@ Or with Docker (recommended):
docker compose -f example-docker-compose.yaml up -d
```
+### Optional dependencies (heavy ML extras)
+
+`poetry install` only installs the **base** dependencies — enough to run BrainAPI with remote LLMs and remote OCR. Heavier components are gated by `.env` flags and live in `[project.optional-dependencies]` groups:
+
+| Group | Triggered by | Adds |
+|---|---|---|
+| `docling-ocr` | `OCR_MODE=docling` in `.env` | `docling`, `accelerate` (~2 GB) for local PDF/DOCX parsing |
+
+Install the right extras based on your current `.env`:
+
+```sh
+make install-extras # auto-detects from .env, installs only what's needed
+make install-extras-all # install every optional group
+make check-extras # exit non-zero if any required extras are missing
+
+# Or call the script directly:
+python scripts/install_extras.py # auto-detect from .env
+python scripts/install_extras.py docling-ocr # force a specific group
+python scripts/install_extras.py --dry-run # print pip command, don't run
+```
+
+If you flip `OCR_MODE=docling` later, just re-run `make install-extras` — pip is a no-op when the deps are already satisfied. The interactive `brainapi` TUI calls the same script under the hood.
+
Then ingest your first data point:
```sh
diff --git a/poetry.lock b/poetry.lock
index 8dcd5a1..a75aa29 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -4151,6 +4151,21 @@ sql-other = ["SQLAlchemy (>=2.0.0)", "adbc-driver-postgresql (>=0.8.0)", "adbc-d
test = ["hypothesis (>=6.46.1)", "pytest (>=7.3.2)", "pytest-xdist (>=2.2.0)"]
xml = ["lxml (>=4.9.2)"]
+[[package]]
+name = "pgvector"
+version = "0.4.2"
+description = "pgvector support for Python"
+optional = false
+python-versions = ">=3.9"
+groups = ["main"]
+files = [
+ {file = "pgvector-0.4.2-py3-none-any.whl", hash = "sha256:549d45f7a18593783d5eec609ea1684a724ba8405c4cb182a0b2b08aeff04e08"},
+ {file = "pgvector-0.4.2.tar.gz", hash = "sha256:322cac0c1dc5d41c9ecf782bd9991b7966685dee3a00bc873631391ed949513a"},
+]
+
+[package.dependencies]
+numpy = "*"
+
[[package]]
name = "pillow"
version = "12.0.0"
@@ -4526,6 +4541,83 @@ files = [
dev = ["abi3audit", "black", "check-manifest", "colorama ; os_name == \"nt\"", "coverage", "packaging", "psleak", "pylint", "pyperf", "pypinfo", "pyreadline3 ; os_name == \"nt\"", "pytest", "pytest-cov", "pytest-instafail", "pytest-xdist", "pywin32 ; os_name == \"nt\" and implementation_name != \"pypy\"", "requests", "rstcheck", "ruff", "setuptools", "sphinx", "sphinx_rtd_theme", "toml-sort", "twine", "validate-pyproject[all]", "virtualenv", "vulture", "wheel", "wheel ; os_name == \"nt\" and implementation_name != \"pypy\"", "wmi ; os_name == \"nt\" and implementation_name != \"pypy\""]
test = ["psleak", "pytest", "pytest-instafail", "pytest-xdist", "pywin32 ; os_name == \"nt\" and implementation_name != \"pypy\"", "setuptools", "wheel ; os_name == \"nt\" and implementation_name != \"pypy\"", "wmi ; os_name == \"nt\" and implementation_name != \"pypy\""]
+[[package]]
+name = "psycopg2-binary"
+version = "2.9.12"
+description = "psycopg2 - Python-PostgreSQL Database Adapter"
+optional = false
+python-versions = ">=3.9"
+groups = ["main"]
+files = [
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:9b818ceff717f98851a64bffd4c5eb5b3059ae280276dcecc52ac658dcf006a4"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:d2fa0d7caca8635c56e373055094eeda3208d901d55dd0ff5abc1d4e47f82b56"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:864c261b3690e1207d14bbfe0a61e27567981b80c47a778561e49f676f7ce433"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c5ee5213445dd45312459029b8c4c0a695461eb517b753d2582315bd07995f5e"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6f9cae1f848779b5b01f417e762c40d026ea93eb0648249a604728cda991dde3"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:63a3ebbd543d3d1eda088ac99164e8c5bac15293ee91f20281fd17d050aee1c4"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:d6fcbba8c9fed08a73b8ac61ea79e4821e45b1e92bb466230c5e746bbf3d5256"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:36512911ebb2b60a0c3e44d0bb5048c1980aced91235d133b7874f3d1d93487c"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:8ffdb59fe88f99589e34354a130217aa1fd2d615612402d6edc8b3dbc7a44463"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:a46fe069b65255df410f856d842bc235f90e22ffdf532dda625fd4213d3fd9b1"},
+ {file = "psycopg2_binary-2.9.12-cp310-cp310-win_amd64.whl", hash = "sha256:ab29414b25dcb698bf26bf213e3348abdcd07bbd5de032a5bec15bd75b298b03"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:5c8ce6c61bd1b1f6b9c24ee32211599f6166af2c55abb19456090a21fd16554b"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:b4a9eaa6e7f4ff91bec10aa3fb296878e75187bced5cc4bafe17dc40915e1326"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:c6528cefc8e50fcc6f4a107e27a672058b36cc5736d665476aeb413ba88dbb06"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:e4e184b1fb6072bf05388aa41c697e1b2d01b3473f107e7ec44f186a32cfd0b8"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4766ab678563054d3f1d064a4db19cc4b5f9e3a8d9018592a8285cf200c248f3"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5a0253224780c978746cb9be55a946bcdaf40fe3519c0f622924cdabdafe2c39"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:0dc9228d47c46bda253d2ecd6bb93b56a9f2d7ad33b684a1fa3622bf74ffe30c"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:f921f3cd87035ef7df233383011d7a53ea1d346224752c1385f1edfd790ceb6a"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:3d999bd982a723113c1a45b55a7a6a90d64d0ed2278020ed625c490ff7bef96c"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:29d4d134bd0ab46ffb04e94aa3c5fa3ef582e9026609165e2f758ff76fc3a3be"},
+ {file = "psycopg2_binary-2.9.12-cp311-cp311-win_amd64.whl", hash = "sha256:cb4a1dacdd48077150dc762a9e5ddbf32c256d66cb46f80839391aa458774936"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:5cdc05117180c5fa9c40eea8ea559ce64d73824c39d928b7da9fb5f6a9392433"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d3227a3bc228c10d21011a99245edca923e4e8bf461857e869a507d9a41fe9f6"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:995ce929eede89db6254b50827e2b7fd61e50d11f0b116b29fffe4a2e53c4580"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:9fe06d93e72f1c048e731a2e3e7854a5bfaa58fc736068df90b352cefe66f03f"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:40e7b28b63aaf737cb3a1edc3a9bbc9a9f4ad3dcb7152e8c1130e4050eddcb7d"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:89d19a9f7899e8eb0656a2b3a08e0da04c720a06db6e0033eab5928aabe60fa9"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:612b965daee295ae2da8f8218ce1d274645dc76ef3f1abf6a0a94fd57eff876d"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:b9a339b79d37c1b45f3235265f07cdeb0cb5ad7acd2ac7720a5920989c17c24e"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:3471336e1acfd9c7fe507b8bad5af9317b6a89294f9eb37bd9a030bb7bebcdc6"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7af18183109e23502c8b2ae7f6926c0882766f35b5175a4cd737ad825e4d7a1b"},
+ {file = "psycopg2_binary-2.9.12-cp312-cp312-win_amd64.whl", hash = "sha256:398fcd4db988c7d7d3713e2b8e18939776fd3fb447052daae4f24fa39daede4c"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:7c729a73c7b1b84de3582f73cdd27d905121dc2c531f3d9a3c32a3011033b965"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:4413d0caef93c5cf50b96863df4c2efe8c269bf2267df353225595e7e15e8df7"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:4dfcf8e45ebb0c663be34a3442f65e17311f3367089cd4e5e3a3e8e62c978777"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c41321a14dd74aceb6a9a643b9253a334521babfa763fa873e33d89cfa122fb5"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:83946ba43979ebfdc99a3cd0ee775c89f221df026984ba19d46133d8d75d3cd9"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:411e85815652d13560fbe731878daa5d92378c4995a22302071890ec3397d019"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:1c8ad4c08e00f7679559eaed7aff1edfffc60c086b976f93972f686384a95e2c"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:00814e40fa23c2b37ef0a1e3c749d89982c73a9cb5046137f0752a22d432e82f"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:98062447aebc20ed20add1f547a364fd0ef8933640d5372ff1873f8deb9b61be"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:66a7685d7e548f10fb4ce32fb01a7b7f4aa702134de92a292c7bd9e0d3dbd290"},
+ {file = "psycopg2_binary-2.9.12-cp313-cp313-win_amd64.whl", hash = "sha256:b6937f5fe4e180aeee87de907a2fa982ded6f7f15d7218f78a083e4e1d68f2a0"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:6f3b3de8a74ef8db215f22edffb19e32dc6fa41340456de7ec99efdc8a7b3ec2"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1006fb62f0f0bc5ce256a832356c6262e91be43f5e4eb15b5eaf38079464caf2"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:840066105706cd2eb29b9a1c2329620056582a4bf3e8169dec5c447042d0869f"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:863f5d12241ebe1c76a72a04c2113b6dc905f90b9cef0e9be0efd994affd9354"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a99eaab34a9010f1a086b126de467466620a750634d114d20455f3a824aae033"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ffdd7dc5463ccd61845ac37b7012d0f35a1548df9febe14f8dd549be4a0bc81e"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:54a0dfecab1b48731f934e06139dfe11e24219fb6d0ceb32177cf0375f14c7b5"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:96937c9c5d891f772430f418a7a8b4691a90c3e6b93cf72b5bd7cad8cbca32a5"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:77b348775efd4cdab410ec6609d81ccecd1139c90265fa583a7255c8064bc03d"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:527e6342b3e44c2f0544f6b8e927d60de7f163f5723b8f1dfa7d2a84298738cd"},
+ {file = "psycopg2_binary-2.9.12-cp314-cp314-win_amd64.whl", hash = "sha256:f12ae41fcafadb39b2785e64a40f9db05d6de2ac114077457e0e7c597f3af980"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:ee2d84ef5eb6c04702d2e9c372ad557fb027f26a5d82804f749dfb14c7fdd2ab"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:cfa2517c94ea3af6deb46f81e1bbd884faa63e28481eb2f889989dd8d95e5f03"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:ba3df2fc42a1cfa45b72cf096d4acb2b885937eedc61461081d53538d4a82a86"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:718e1fc18edf573b02cb8aea868de8d8d33f99ce9620206aa9144b67b0985e94"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5c7cb4cbf894a1d36c720d713de507952c7c58f66d30834708f03dbe5c822ccf"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-manylinux_2_38_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:049366c6d884bdcd65d66e6ca1fdbebe670b56c6c9ba46f164e6667e90881964"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:fb1828cf3da68f99e45ebce1355d65d2d12b6a78fb5dfb16247aad6bdef5f5d2"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-musllinux_1_2_ppc64le.whl", hash = "sha256:127467c6e476dd876634f17c3d870530e73ff454ff99bff73d36e80af28e1115"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-musllinux_1_2_riscv64.whl", hash = "sha256:ace94261f43850e9e79f6c56636c5e0147978ab79eda5e5e5ebf13ae146fc8fe"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:a7e39a65b7d2a20e4ba2e0aaad1960b61cc2888d6ab047769f8347bd3c9ad915"},
+ {file = "psycopg2_binary-2.9.12-cp39-cp39-win_amd64.whl", hash = "sha256:f625abb7020e4af3432d95342daa1aa0db3fa369eed19807aa596367ba791b10"},
+ {file = "psycopg2_binary-2.9.12.tar.gz", hash = "sha256:5ac9444edc768c02a6b6a591f070b8aae28ff3a99be57560ac996001580f294c"},
+]
+
[[package]]
name = "pyarrow"
version = "21.0.0"
@@ -8303,4 +8395,4 @@ cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and pyt
[metadata]
lock-version = "2.1"
python-versions = ">=3.11,<4.0.0"
-content-hash = "a049b7b5ef119f763b080f3a27b043cc74a0d29b0e98f009263e7a89a84761e4"
+content-hash = "8c734c10f53d08e1644a6368a7e0a22a1bca52b0136962906db9436ad5d88552"
diff --git a/pyproject.toml b/pyproject.toml
index 418c804..9c7f992 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,6 +12,9 @@ dependencies = [
"pymongo (>=4.15.3,<5.0.0)",
"cpp-chunker (>=0.1.4,<0.2.0)",
"neo4j (>=6.0.2,<7.0.0)",
+ "networkx (>=3.0,<4.0.0)",
+ "psycopg2-binary (>=2.9.6,<3.0.0)",
+ "pgvector (>=0.3.0,<1.0.0)",
"pylint (>=4.0.1,<5.0.0)",
"langchain (>=1.0.0,<2.0.0)",
"openai (>=2.5.0,<3.0.0)",
@@ -36,9 +39,20 @@ dependencies = [
"spacy_langdetect (>=0.1.2,<0.2.0)",
"langid (>=1.1.6,<2.0.0)",
"mcp (>=1.26.0,<2.0.0)",
+ "boto3 (>=1.36.0,<2.0.0)",
+ "langchain-aws (>=0.2.0,<1.0.0)",
+]
+
+[project.optional-dependencies]
+docling-ocr = [
"docling (>=2.0.0,<3.0.0)",
"accelerate (>=1.0.0,<2.0.0)",
]
+postgresql-backend = [
+ "psycopg2-binary (>=2.9.6,<3.0.0)",
+ "pgvector (>=0.3.0,<1.0.0)",
+ "networkx (>=3.0,<4.0.0)",
+]
[tool.poetry]
package-mode = false
@@ -49,6 +63,9 @@ redis = ">=6.4.0,<7.0.0"
pymongo = ">=4.15.3,<5.0.0"
cpp-chunker = ">=0.1.4,<0.2.0"
neo4j = ">=6.0.2,<7.0.0"
+networkx = ">=3.0,<4.0.0"
+psycopg2-binary = ">=2.9.6,<3.0.0"
+pgvector = ">=0.3.0,<1.0.0"
pylint = ">=4.0.1,<5.0.0"
langchain = ">=1.0.0,<2.0.0"
openai = ">=2.5.0,<3.0.0"
@@ -74,6 +91,13 @@ typer = ">=0.12.0,<0.15.0"
spacy_langdetect = ">=0.1.2,<0.2.0"
langid = ">=1.1.6,<2.0.0"
mcp = ">=1.26.0,<2.0.0"
+boto3 = ">=1.36.0,<2.0.0"
+langchain-aws = ">=0.2.0,<1.0.0"
+
+[tool.poetry.group.docling-ocr]
+optional = true
+
+[tool.poetry.group.docling-ocr.dependencies]
docling = ">=2.0.0,<3.0.0"
accelerate = ">=1.0.0,<2.0.0"
diff --git a/scripts/install_extras.py b/scripts/install_extras.py
new file mode 100644
index 0000000..82956c5
--- /dev/null
+++ b/scripts/install_extras.py
@@ -0,0 +1,297 @@
+"""
+Install only the pyproject.toml optional-dependency groups that the active
+.env requires.
+
+Usage (no TUI required):
+
+ python scripts/install_extras.py # auto-detect from .env
+ python scripts/install_extras.py docling-ocr # force a specific group
+ python scripts/install_extras.py --all # install every optional group
+ python scripts/install_extras.py --dry-run # print pip command, don't run
+ python scripts/install_extras.py --check # exit non-zero if missing
+
+Reads ./.env (or $BRAINAPI_DOTENV) for OCR_MODE and any future toggles, then
+calls `python -m pip install` against the active interpreter with the matching
+specs from pyproject.toml's [project.optional-dependencies].
+
+Safe to re-run: pip is a no-op when the specs are already satisfied.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+ import tomllib
+except ModuleNotFoundError:
+ import tomli as tomllib # type: ignore[no-redef]
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PYPROJECT_PATH = REPO_ROOT / "pyproject.toml"
+DEFAULT_ENV_PATH = Path(os.environ.get("BRAINAPI_DOTENV", REPO_ROOT / ".env"))
+
+
+def parse_dotenv(path: Path) -> dict[str, str]:
+ if not path.exists():
+ return {}
+ result: dict[str, str] = {}
+ for raw in path.read_text(encoding="utf-8").splitlines():
+ line = raw.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, value = line.partition("=")
+ result[key.strip()] = value.strip().strip('"').strip("'")
+ return result
+
+
+def _load_pyproject() -> dict:
+ if not PYPROJECT_PATH.exists():
+ return {}
+ with PYPROJECT_PATH.open("rb") as fh:
+ return tomllib.load(fh)
+
+
+def _poetry_dep_to_spec(name: str, value) -> str | None:
+ if name == "python":
+ return None
+ if isinstance(value, str):
+ return name if value == "*" else f"{name}{value}"
+ if isinstance(value, dict):
+ version = value.get("version", "")
+ extras = value.get("extras", []) or []
+ head = name + (f"[{','.join(extras)}]" if extras else "")
+ if not version or version == "*":
+ return head
+ return f"{head}{version}"
+ return None
+
+
+def load_base_deps() -> list[str]:
+ data = _load_pyproject()
+ project_deps = data.get("project", {}).get("dependencies", []) or []
+ if project_deps:
+ return list(project_deps)
+ poetry_deps = (
+ data.get("tool", {}).get("poetry", {}).get("dependencies", {}) or {}
+ )
+ out: list[str] = []
+ for name, value in poetry_deps.items():
+ spec = _poetry_dep_to_spec(name, value)
+ if spec:
+ out.append(spec)
+ return out
+
+
+def load_optional_groups() -> dict[str, list[str]]:
+ data = _load_pyproject()
+ project_optional = (
+ data.get("project", {}).get("optional-dependencies", {}) or {}
+ )
+ if project_optional:
+ return {k: list(v) for k, v in project_optional.items()}
+ poetry_groups = data.get("tool", {}).get("poetry", {}).get("group", {}) or {}
+ out: dict[str, list[str]] = {}
+ for group_name, group_value in poetry_groups.items():
+ if not isinstance(group_value, dict):
+ continue
+ deps = group_value.get("dependencies", {}) or {}
+ specs: list[str] = []
+ for name, value in deps.items():
+ spec = _poetry_dep_to_spec(name, value)
+ if spec:
+ specs.append(spec)
+ if specs:
+ out[group_name] = specs
+ return out
+
+
+POSTGRESQL_BACKEND_SPECS = [
+ "psycopg2-binary>=2.9.6,<3.0.0",
+ "pgvector>=0.3.0,<1.0.0",
+ "networkx>=3.0,<4.0.0",
+]
+
+
+def uses_postgresql_backend(env: dict[str, str]) -> bool:
+ vector = env.get("VECTOR_DB", "milvus").lower()
+ data = env.get("DATA_DB", "mongo").lower()
+ graph = env.get("GRAPH_DB", "neo4j").lower()
+ return vector == "postgresql" or data == "postgresql" or graph == "networkx"
+
+
+def required_groups(env: dict[str, str]) -> list[str]:
+ groups: list[str] = []
+ if env.get("OCR_MODE", "docparser").lower() == "docling":
+ groups.append("docling-ocr")
+ if uses_postgresql_backend(env):
+ groups.append("postgresql-backend")
+ return groups
+
+
+def required_backend_specs(env: dict[str, str]) -> list[str]:
+ if not uses_postgresql_backend(env):
+ return []
+ optional = load_optional_groups()
+ if "postgresql-backend" in optional:
+ return []
+ return list(POSTGRESQL_BACKEND_SPECS)
+
+
+def package_name_from_spec(spec: str) -> str:
+ spec = spec.strip()
+ match = re.match(r"^([A-Za-z0-9][A-Za-z0-9._-]*)", spec)
+ if match:
+ return match.group(1)
+ return spec
+
+
+def package_installed(name: str) -> bool:
+ pkg = package_name_from_spec(name)
+ try:
+ from importlib.metadata import PackageNotFoundError, version
+
+ version(pkg)
+ return True
+ except PackageNotFoundError:
+ pass
+ except Exception:
+ pass
+ import_names = {pkg.replace("-", "_"), pkg}
+ if pkg == "psycopg2-binary":
+ import_names.add("psycopg2")
+ return any(importlib.util.find_spec(c) is not None for c in import_names)
+
+
+def filter_missing(specs: list[str]) -> list[str]:
+ return [s for s in specs if not package_installed(package_name_from_spec(s))]
+
+
+def install_specs(specs: list[str], dry_run: bool) -> int:
+ if not specs:
+ return 0
+ cmd = [sys.executable, "-m", "pip", "install", *specs]
+ print(f"$ {' '.join(cmd)}")
+ if dry_run:
+ return 0
+ return subprocess.call(cmd)
+
+
+def main(argv: list[str]) -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "groups",
+ nargs="*",
+ help="Optional groups to install. Omit to auto-detect from .env.",
+ )
+ parser.add_argument(
+ "--env-file",
+ default=str(DEFAULT_ENV_PATH),
+ help="Path to .env (default: ./.env, or $BRAINAPI_DOTENV).",
+ )
+ parser.add_argument(
+ "--dry-run", action="store_true",
+ help="Print the pip command without running it.",
+ )
+ parser.add_argument(
+ "--check", action="store_true",
+ help="Exit non-zero if any required extras are missing; do not install.",
+ )
+ parser.add_argument(
+ "--all", action="store_true",
+ help="Install every optional group declared in pyproject.toml.",
+ )
+ parser.add_argument(
+ "--include-base", action="store_true",
+ help="Also install [project].dependencies / [tool.poetry.dependencies] base deps.",
+ )
+ parser.add_argument(
+ "--upgrade-pip", action="store_true",
+ help="Run `pip install --upgrade pip` before installing anything.",
+ )
+ args = parser.parse_args(argv)
+
+ optional_groups = load_optional_groups()
+
+ if args.all:
+ wanted = list(optional_groups.keys())
+ elif args.groups:
+ wanted = args.groups
+ else:
+ env = parse_dotenv(Path(args.env_file))
+ wanted = required_groups(env)
+ if wanted:
+ print(f"Auto-detected required groups from {args.env_file}: {wanted}")
+ elif not args.include_base:
+ print(
+ f"No optional groups required by {args.env_file} "
+ f"(OCR_MODE={env.get('OCR_MODE', 'docparser')}).",
+ )
+
+ unknown = [g for g in wanted if g not in optional_groups]
+ known = [g for g in wanted if g in optional_groups]
+ if unknown:
+ print(
+ f"Skipping optional groups not declared in pyproject.toml: {unknown}",
+ file=sys.stderr,
+ )
+ if optional_groups:
+ print(
+ f"Available optional groups: {list(optional_groups.keys())}",
+ file=sys.stderr,
+ )
+ else:
+ print(
+ "No optional-dependency groups are declared in pyproject.toml. "
+ "These packages may already be part of base dependencies — "
+ "continuing without them.",
+ file=sys.stderr,
+ )
+
+ wanted = known
+ extra_specs: list[str] = []
+ for g in wanted:
+ extra_specs.extend(optional_groups[g])
+
+ env = parse_dotenv(Path(args.env_file))
+ backend_specs = (
+ required_backend_specs(env) if not args.groups and not args.all else []
+ )
+
+ if args.check:
+ missing = filter_missing([*extra_specs, *backend_specs])
+ if missing:
+ print(f"Missing extras: {missing}", file=sys.stderr)
+ hint_groups = wanted or (
+ ["postgresql-backend"] if backend_specs else []
+ )
+ if hint_groups:
+ print(
+ f"Install them with: {sys.executable} "
+ f"scripts/install_extras.py {' '.join(hint_groups)}",
+ file=sys.stderr,
+ )
+ return 1
+ print("All required extras are installed.")
+ return 0
+
+ base_specs = load_base_deps() if args.include_base else []
+ all_specs = [*base_specs, *extra_specs, *backend_specs]
+
+ if not all_specs:
+ return 0
+
+ if args.upgrade_pip and not args.dry_run:
+ subprocess.call([sys.executable, "-m", "pip", "install", "--upgrade", "pip"])
+
+ return install_specs(all_specs, args.dry_run)
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/src/config.py b/src/config.py
index 4473283..b8352b9 100644
--- a/src/config.py
+++ b/src/config.py
@@ -3,7 +3,7 @@ File: /config.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Wednesday March 4th 2026 9:35:41 pm
+Last Modified: Sunday March 29th 2026 3:27:28 am
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -24,28 +24,74 @@ dotenv.load_dotenv(dotenv_path=_env_path)
logger = logging.getLogger(__name__)
+def _normalize_openai_base_url(raw: str | None) -> str | None:
+ if not raw or not raw.strip():
+ return None
+ normalized = raw.strip().rstrip("/")
+ if normalized in ("https://api.openai.com/v1", "https://api.openai.com"):
+ return None
+ return normalized
+
+
class AzureConfig:
"""
Configuration class for the Azure configuration.
"""
def __init__(self):
+ self.small_llm_model = os.getenv("AZURE_SMALL_LLM_MODEL", "gpt-4o-mini")
self.large_llm_model = os.getenv("AZURE_LARGE_LLM_MODEL")
- self.large_llm_api_version = os.getenv("AZURE_LARGE_LLM_API_VERSION")
- self.large_llm_endpoint = os.getenv("AZURE_LARGE_LLM_ENDPOINT")
- self.large_llm_subscription_key = os.getenv("AZURE_LARGE_LLM_SUBSCRIPTION_KEY")
+ self.llm_api_version = os.getenv("AZURE_LLM_API_VERSION") or os.getenv(
+ "AZURE_LARGE_LLM_API_VERSION"
+ )
+ self.llm_endpoint = os.getenv("AZURE_LLM_ENDPOINT") or os.getenv(
+ "AZURE_LARGE_LLM_ENDPOINT"
+ )
+ self.llm_subscription_key = os.getenv("AZURE_LLM_SUBSCRIPTION_KEY") or os.getenv(
+ "AZURE_LARGE_LLM_SUBSCRIPTION_KEY"
+ )
+ self.embedding_model = os.getenv("AZURE_EMBEDDING_MODEL", "text-embedding-3-large")
self.embedding_full_endpoint = os.getenv("AZURE_EMBEDDING_FULL_ENDPOINT")
self.embedding_key = os.getenv("AZURE_EMBEDDING_KEY")
+ def validate_llm(self):
if [
+ self.small_llm_model,
self.large_llm_model,
- self.large_llm_api_version,
- self.large_llm_endpoint,
- self.large_llm_subscription_key,
- self.embedding_full_endpoint,
- self.embedding_key,
+ self.llm_api_version,
+ self.llm_endpoint,
+ self.llm_subscription_key,
].count(None) > 0:
- raise ValueError("Azure configuration is not complete")
+ raise ValueError("Azure LLM configuration is not complete")
+
+ def validate_embeddings(self):
+ if [self.embedding_full_endpoint, self.embedding_key].count(None) > 0:
+ raise ValueError("Azure embeddings configuration is not complete")
+
+
+class OpenAIConfig:
+ def __init__(self):
+ self.api_key = os.getenv("OPENAI_API_KEY")
+ self.base_url = _normalize_openai_base_url(os.getenv("OPENAI_BASE_URL"))
+ self.small_llm_model = os.getenv("OPENAI_SMALL_LLM_MODEL", "gpt-4o-mini")
+ self.large_llm_model = os.getenv("OPENAI_LARGE_LLM_MODEL", "gpt-4o")
+ self.embedding_model = os.getenv(
+ "OPENAI_EMBEDDING_MODEL", "text-embedding-3-large"
+ )
+
+ def validate_llm(self, require_large: bool):
+ if not self.api_key:
+ raise ValueError("OpenAI API key is not set")
+ if not self.small_llm_model:
+ raise ValueError("OpenAI small LLM model is not set")
+ if require_large and not self.large_llm_model:
+ raise ValueError("OpenAI large LLM model is not set")
+
+ def validate_embeddings(self):
+ if not self.api_key:
+ raise ValueError("OpenAI API key is not set")
+ if not self.embedding_model:
+ raise ValueError("OpenAI embedding model is not set")
class GCPConfig:
@@ -64,20 +110,61 @@ class GCPConfig:
if not os.path.isabs(credentials_path):
credentials_path = str(Path(__file__).parent.parent / credentials_path)
- if not os.path.exists(credentials_path):
- raise FileNotFoundError(
- f"Credentials file not found at: {credentials_path}. "
- "Please set GCP_CREDENTIALS_PATH environment variable or place gcp_credentials.json in the project root."
- )
logger.debug("GCP credentials_path: %s", credentials_path)
self.credentials_path = credentials_path
self.project_id = os.getenv("GCP_PROJECT_ID")
self.small_llm_model = os.getenv("GCP_SMALL_LLM_MODEL")
+ self.large_llm_model = os.getenv("GCP_LARGE_LLM_MODEL")
+ self.embedding_model = os.getenv("GCP_EMBEDDING_MODEL", "text-embedding-005")
+
+ def validate_llm(self, require_large: bool):
+ if not os.path.exists(self.credentials_path):
+ raise FileNotFoundError(
+ f"Credentials file not found at: {self.credentials_path}. "
+ "Please set GCP_CREDENTIALS_PATH environment variable or place gcp_credentials.json in the project root."
+ )
+ required = [self.credentials_path, self.project_id, self.small_llm_model]
+ if require_large:
+ required.append(self.large_llm_model)
+ if required.count(None) > 0:
+ raise ValueError("GCP LLM configuration is not complete")
+
+ def validate_embeddings(self):
+ if not os.path.exists(self.credentials_path):
+ raise FileNotFoundError(
+ f"Credentials file not found at: {self.credentials_path}. "
+ "Please set GCP_CREDENTIALS_PATH environment variable or place gcp_credentials.json in the project root."
+ )
+ if [self.credentials_path, self.project_id, self.embedding_model].count(None) > 0:
+ raise ValueError("GCP embeddings configuration is not complete")
- if [self.credentials_path, self.project_id, self.small_llm_model].count(
- None
- ) > 0:
- raise ValueError("GCP configuration is not complete")
+
+class BedrockConfig:
+ def __init__(self):
+ self.region = os.getenv("BEDROCK_REGION")
+ self.access_key_id = os.getenv("BEDROCK_ACCESS_KEY_ID")
+ self.secret_access_key = os.getenv("BEDROCK_SECRET_ACCESS_KEY")
+ self.session_token = os.getenv("BEDROCK_SESSION_TOKEN")
+ self.small_llm_model = os.getenv("BEDROCK_SMALL_LLM_MODEL")
+ self.large_llm_model = os.getenv("BEDROCK_LARGE_LLM_MODEL")
+ self.embedding_model = os.getenv("BEDROCK_EMBEDDING_MODEL")
+
+ def _validate_auth(self):
+ if [self.region, self.access_key_id, self.secret_access_key].count(None) > 0:
+ raise ValueError("Bedrock authentication is not complete")
+
+ def validate_llm(self, require_large: bool):
+ self._validate_auth()
+ required = [self.small_llm_model]
+ if require_large:
+ required.append(self.large_llm_model)
+ if required.count(None) > 0:
+ raise ValueError("Bedrock LLM configuration is not complete")
+
+ def validate_embeddings(self):
+ self._validate_auth()
+ if [self.embedding_model].count(None) > 0:
+ raise ValueError("Bedrock embeddings configuration is not complete")
class RedisConfig:
@@ -109,6 +196,55 @@ class Neo4jConfig:
raise ValueError("Neo4j configuration is not complete")
+class PostgreSQLConfig:
+ """
+ Configuration class for the PostgreSQL graph / data / vector stores.
+
+ BrainAPI uses one Postgres database per brain. Two cluster-level names are
+ therefore needed beyond the connection credentials:
+
+ * ``system_database`` — the registry database (mirrors Mongo's
+ ``MONGO_SYSTEM_DATABASE``). It stores the ``data_brains`` table that
+ catalogs every brain alongside its PAT and metadata.
+ * ``maintenance_database`` — the database used solely for
+ ``CREATE DATABASE`` statements when a new brain is provisioned. Almost
+ every cluster ships with ``postgres`` available for this role.
+
+ ``POSTGRES_DATABASE`` is retained as the source of truth for the system
+ database to preserve backwards compatibility with existing deployments.
+ ``POSTGRES_SYSTEM_DATABASE`` takes precedence when set explicitly.
+ """
+
+ def __init__(self):
+ self.host = os.getenv("POSTGRES_HOST")
+ port_str = os.getenv("POSTGRES_PORT")
+ self.port = int(port_str) if port_str else None
+ self.username = os.getenv("POSTGRES_USERNAME")
+ self.password = os.getenv("POSTGRES_PASSWORD")
+
+ system_db = os.getenv("POSTGRES_SYSTEM_DATABASE") or os.getenv(
+ "POSTGRES_DATABASE"
+ )
+ self.system_database = system_db
+ self.database = system_db
+ self.maintenance_database = os.getenv(
+ "POSTGRES_MAINTENANCE_DATABASE", "postgres"
+ )
+
+ def validate_credentials(self) -> None:
+ """Validate only what is required to open a Postgres connection."""
+ if [self.host, self.port, self.username, self.password].count(None) > 0:
+ raise ValueError("PostgreSQL connection configuration is not complete")
+
+ def validate(self) -> None:
+ self.validate_credentials()
+ if not self.system_database:
+ raise ValueError(
+ "PostgreSQL system database is not configured "
+ "(set POSTGRES_DATABASE or POSTGRES_SYSTEM_DATABASE)"
+ )
+
+
class MilvusConfig:
"""
Configuration class for the Milvus configuration.
@@ -132,8 +268,6 @@ class EmbeddingsConfig:
"""
def __init__(self, mode: str):
- self.full_endpoint = os.getenv("EMBEDDINGS_FULL_ENDPOINT")
- self.key = os.getenv("EMBEDDINGS_KEY")
self.local_model = os.getenv("EMBEDDINGS_LOCAL_MODEL")
self.small_model = os.getenv("EMBEDDINGS_SMALL_MODEL")
@@ -159,30 +293,16 @@ class EmbeddingsConfig:
else None
)
- if mode == "local":
- if [
- self.local_model,
- self.small_model,
- self.embedding_nodes_dimension,
- self.embedding_triplets_dimension,
- self.embedding_observations_dimension,
- self.embedding_data_dimension,
- self.embedding_relationships_dimension,
- ].count(None) > 0:
- raise ValueError("Embeddings configuration is not complete (local)")
- else:
- if [
- self.full_endpoint,
- self.key,
- self.local_model,
- self.small_model,
- self.embedding_nodes_dimension,
- self.embedding_triplets_dimension,
- self.embedding_observations_dimension,
- self.embedding_data_dimension,
- self.embedding_relationships_dimension,
- ].count(None) > 0:
- raise ValueError("Embeddings configuration is not complete")
+ if [
+ self.local_model,
+ self.small_model,
+ self.embedding_nodes_dimension,
+ self.embedding_triplets_dimension,
+ self.embedding_observations_dimension,
+ self.embedding_data_dimension,
+ self.embedding_relationships_dimension,
+ ].count(None) > 0:
+ raise ValueError("Embeddings configuration is not complete")
class MongoConfig:
@@ -269,6 +389,7 @@ class SpacyConfig:
_MODES = ("local", "remote")
+_PROVIDERS = ("ollama", "azure", "openai", "gcp_vertex", "amazon_bedrock")
class Config:
@@ -293,23 +414,91 @@ class Config:
if self.models_mode not in _MODES:
raise ValueError(f"Invalid MODELS_MODE: {self.models_mode}")
- if self.models_mode == "local":
- self.azure = None
- self.gcp = None
- self.embeddings = EmbeddingsConfig(mode="local")
- else:
- self.azure = AzureConfig()
- self.gcp = GCPConfig()
- self.embeddings = EmbeddingsConfig(mode="remote")
+ default_small_provider = "ollama" if self.models_mode == "local" else "gcp_vertex"
+ default_large_provider = "ollama" if self.models_mode == "local" else "azure"
+ default_embeddings_provider = (
+ "ollama" if self.models_mode == "local" else "azure"
+ )
+
+ self.llm_small_provider = os.getenv("LLM_SMALL_PROVIDER", default_small_provider)
+ self.llm_large_provider = os.getenv("LLM_LARGE_PROVIDER", default_large_provider)
+ self.embeddings_provider = os.getenv(
+ "EMBEDDINGS_PROVIDER", default_embeddings_provider
+ )
+
+ for provider in (
+ self.llm_small_provider,
+ self.llm_large_provider,
+ self.embeddings_provider,
+ ):
+ if provider not in _PROVIDERS:
+ raise ValueError(f"Invalid provider: {provider}")
+
+ use_azure_llm = self.llm_small_provider == "azure" or self.llm_large_provider == "azure"
+ use_azure_embeddings = self.embeddings_provider == "azure"
+ use_gcp_llm = self.llm_small_provider == "gcp_vertex" or self.llm_large_provider == "gcp_vertex"
+ use_gcp_large = self.llm_large_provider == "gcp_vertex"
+ use_gcp_embeddings = self.embeddings_provider == "gcp_vertex"
+ use_bedrock_llm = (
+ self.llm_small_provider == "amazon_bedrock"
+ or self.llm_large_provider == "amazon_bedrock"
+ )
+ use_bedrock_large = self.llm_large_provider == "amazon_bedrock"
+ use_bedrock_embeddings = self.embeddings_provider == "amazon_bedrock"
+ use_openai_llm = (
+ self.llm_small_provider == "openai" or self.llm_large_provider == "openai"
+ )
+ use_openai_large = self.llm_large_provider == "openai"
+ use_openai_embeddings = self.embeddings_provider == "openai"
+ use_ollama = (
+ self.llm_small_provider == "ollama"
+ or self.llm_large_provider == "ollama"
+ or self.embeddings_provider == "ollama"
+ )
+
+ self.azure = AzureConfig() if use_azure_llm or use_azure_embeddings else None
+ if self.azure is not None:
+ if use_azure_llm:
+ self.azure.validate_llm()
+ if use_azure_embeddings:
+ self.azure.validate_embeddings()
+
+ self.gcp = GCPConfig() if use_gcp_llm or use_gcp_embeddings else None
+ if self.gcp is not None:
+ if use_gcp_llm:
+ self.gcp.validate_llm(require_large=use_gcp_large)
+ if use_gcp_embeddings:
+ self.gcp.validate_embeddings()
+
+ self.bedrock = BedrockConfig() if use_bedrock_llm or use_bedrock_embeddings else None
+ if self.bedrock is not None:
+ if use_bedrock_llm:
+ self.bedrock.validate_llm(require_large=use_bedrock_large)
+ if use_bedrock_embeddings:
+ self.bedrock.validate_embeddings()
+
+ self.openai = OpenAIConfig() if use_openai_llm or use_openai_embeddings else None
+ if self.openai is not None:
+ if use_openai_llm:
+ self.openai.validate_llm(require_large=use_openai_large)
+ if use_openai_embeddings:
+ self.openai.validate_embeddings()
+
+ self.ollama = OllamaConfig() if use_ollama else None
+ self.embeddings = EmbeddingsConfig(mode=self.models_mode)
+
+ self.vector_db = os.getenv("VECTOR_DB", "milvus")
+ self.data_db = os.getenv("DATA_DB", "mongo")
+ self.graph_db = os.getenv("GRAPH_DB", "neo4j")
self.redis = RedisConfig()
self.neo4j = Neo4jConfig()
+ self.postgresql = PostgreSQLConfig()
self.milvus = MilvusConfig()
self.mongo = MongoConfig()
self.celery = CeleryConfig()
self.pricing = PricingConfig()
self.spacy = SpacyConfig()
- self.ollama = OllamaConfig()
self.run_graph_consolidator = (
os.getenv("RUN_GRAPH_CONSOLIDATOR", "true") == "true"
diff --git a/src/core/instances.py b/src/core/instances.py
index a751a9c..2619eb7 100644
--- a/src/core/instances.py
+++ b/src/core/instances.py
@@ -4,37 +4,84 @@ from src.adapters.embeddings import EmbeddingsAdapter, VectorStoreAdapter
from src.adapters.graph import GraphAdapter
from src.adapters.llm import LLMAdapter
from src.config import config
-from src.lib.milvus.client import _milvus_client
-from src.lib.mongo.client import _mongo_client
-from src.lib.neo4j.client import _neo4j_client
from src.lib.redis.client import _redis_client
-_MODES = ("local", "remote")
+def _build_small_llm(provider: str):
+ if provider == "ollama":
+ from src.lib.llm.client_ollama import _llm_small_client
+ return _llm_small_client
+ if provider == "azure":
+ from src.lib.llm.client_azure import _llm_small_client_azure
-def _require_mode():
- if config.models_mode not in _MODES:
- raise ValueError(f"Invalid models mode: {config.models_mode}")
- return config.models_mode == "local"
+ return _llm_small_client_azure
+ if provider == "openai":
+ from src.lib.llm.client_openai import _llm_small_client_openai
+ return _llm_small_client_openai
+ if provider == "gcp_vertex":
+ from src.lib.llm.client_small import _llm_small_client
-_is_local = _require_mode()
+ return _llm_small_client
+ if provider == "amazon_bedrock":
+ from src.lib.llm.client_bedrock import _llm_small_client_bedrock
-if _is_local:
- from src.lib.llm.client_ollama import _llm_large_client, _llm_small_client
+ return _llm_small_client_bedrock
+ raise ValueError(f"Unsupported small LLM provider: {provider}")
- _llm_small = LLMAdapter()
- _llm_small.add_client(_llm_small_client)
- _llm_large = LLMAdapter()
- _llm_large.add_client(_llm_large_client)
-else:
- from src.lib.llm.client_large import _llm_large_client
- from src.lib.llm.client_small import _llm_small_client
- _llm_small = LLMAdapter()
- _llm_small.add_client(_llm_small_client)
- _llm_large = LLMAdapter()
- _llm_large.add_client(_llm_large_client)
+def _build_large_llm(provider: str):
+ if provider == "ollama":
+ from src.lib.llm.client_ollama import _llm_large_client
+
+ return _llm_large_client
+ if provider == "azure":
+ from src.lib.llm.client_large import _llm_large_client
+
+ return _llm_large_client
+ if provider == "openai":
+ from src.lib.llm.client_openai import _llm_large_client_openai
+
+ return _llm_large_client_openai
+ if provider == "gcp_vertex":
+ from src.lib.llm.client_vertex import _llm_large_client_vertex
+
+ return _llm_large_client_vertex
+ if provider == "amazon_bedrock":
+ from src.lib.llm.client_bedrock import _llm_large_client_bedrock
+
+ return _llm_large_client_bedrock
+ raise ValueError(f"Unsupported large LLM provider: {provider}")
+
+
+def _build_embeddings(provider: str):
+ if provider == "ollama":
+ from src.lib.embeddings.client_ollama import _embeddings_ollama_client
+
+ return _embeddings_ollama_client
+ if provider == "azure":
+ from src.lib.embeddings.client import _embeddings_client
+
+ return _embeddings_client
+ if provider == "openai":
+ from src.lib.embeddings.client_openai import _embeddings_openai_client
+
+ return _embeddings_openai_client
+ if provider == "gcp_vertex":
+ from src.lib.embeddings.client_vertex import _embeddings_vertex_client
+
+ return _embeddings_vertex_client
+ if provider == "amazon_bedrock":
+ from src.lib.embeddings.client_bedrock import _embeddings_bedrock_client
+
+ return _embeddings_bedrock_client
+ raise ValueError(f"Unsupported embeddings provider: {provider}")
+
+
+_llm_small = LLMAdapter()
+_llm_small.add_client(_build_small_llm(config.llm_small_provider))
+_llm_large = LLMAdapter()
+_llm_large.add_client(_build_large_llm(config.llm_large_provider))
llm_small_adapter = _llm_small
llm_large_adapter = _llm_large
@@ -43,30 +90,43 @@ cache_adapter = CacheAdapter()
cache_adapter.add_client(_redis_client)
graph_adapter = GraphAdapter()
-graph_adapter.add_client(_neo4j_client)
+if config.graph_db == "neo4j":
+ from src.lib.neo4j.client import _neo4j_client
+
+ graph_adapter.add_client(_neo4j_client)
+elif config.graph_db == "networkx":
+ from src.lib.postgresql.networkx import get_networkx_graph_client
-data_adapter = DataAdapter()
-data_adapter.add_client(_mongo_client)
+ graph_adapter.add_client(get_networkx_graph_client())
-if _is_local:
- from src.lib.embeddings.local import _embeddings_local_client
- from src.lib.embeddings.client_small import _embeddings_small_client
+if config.data_db == "mongo":
+ from src.lib.mongo.client import _mongo_client
- _embeddings_primary = EmbeddingsAdapter()
- _embeddings_primary.add_client(_embeddings_local_client)
- _embeddings_small = EmbeddingsAdapter()
- _embeddings_small.add_client(_embeddings_small_client)
-else:
- from src.lib.embeddings.client import _embeddings_client
- from src.lib.embeddings.client_small import _embeddings_small_client
+ data_adapter = DataAdapter()
+ data_adapter.add_client(_mongo_client)
+elif config.data_db == "postgresql":
+ from src.lib.postgresql.data import get_postgresql_data_client
- _embeddings_primary = EmbeddingsAdapter()
- _embeddings_primary.add_client(_embeddings_client)
- _embeddings_small = EmbeddingsAdapter()
- _embeddings_small.add_client(_embeddings_small_client)
+ data_adapter = DataAdapter()
+ data_adapter.add_client(get_postgresql_data_client())
+
+from src.lib.embeddings.client_small import _embeddings_small_client
+
+_embeddings_primary = EmbeddingsAdapter()
+_embeddings_primary.add_client(_build_embeddings(config.embeddings_provider))
+_embeddings_small = EmbeddingsAdapter()
+_embeddings_small.add_client(_embeddings_small_client)
embeddings_adapter = _embeddings_primary
embeddings_small_adapter = _embeddings_small
-vector_store_adapter = VectorStoreAdapter()
-vector_store_adapter.add_client(_milvus_client)
+if config.vector_db == "milvus":
+ from src.lib.milvus.client import _milvus_client
+
+ vector_store_adapter = VectorStoreAdapter()
+ vector_store_adapter.add_client(_milvus_client)
+elif config.vector_db == "postgresql":
+ from src.lib.postgresql.vectors import get_postgresql_vector_store_client
+
+ vector_store_adapter = VectorStoreAdapter()
+ vector_store_adapter.add_client(get_postgresql_vector_store_client())
diff --git a/src/lib/embeddings/client_bedrock.py b/src/lib/embeddings/client_bedrock.py
new file mode 100644
index 0000000..1d652e8
--- /dev/null
+++ b/src/lib/embeddings/client_bedrock.py
@@ -0,0 +1,38 @@
+import json
+
+import boto3
+
+from src.adapters.interfaces.embeddings import EmbeddingsClient
+from src.config import config
+
+
+class BedrockEmbeddingsClient(EmbeddingsClient):
+ def __init__(self):
+ session = boto3.Session(
+ aws_access_key_id=config.bedrock.access_key_id,
+ aws_secret_access_key=config.bedrock.secret_access_key,
+ aws_session_token=config.bedrock.session_token,
+ region_name=config.bedrock.region,
+ )
+ self.client = session.client("bedrock-runtime")
+ self.model = config.bedrock.embedding_model
+
+ def _embed_one(self, text: str) -> list[float]:
+ body = json.dumps({"inputText": text})
+ response = self.client.invoke_model(
+ modelId=self.model,
+ body=body,
+ contentType="application/json",
+ accept="application/json",
+ )
+ payload = json.loads(response["body"].read())
+ return payload["embedding"]
+
+ def embed_text(self, text: str) -> list[float]:
+ return self._embed_one(text)
+
+ def embed_texts(self, texts: list[str]) -> list[list[float]]:
+ return [self._embed_one(text) for text in texts]
+
+
+_embeddings_bedrock_client = BedrockEmbeddingsClient()
diff --git a/src/lib/embeddings/client_ollama.py b/src/lib/embeddings/client_ollama.py
new file mode 100644
index 0000000..81472ae
--- /dev/null
+++ b/src/lib/embeddings/client_ollama.py
@@ -0,0 +1,25 @@
+from openai import OpenAI
+
+from src.adapters.interfaces.embeddings import EmbeddingsClient
+from src.config import config
+
+
+class OllamaEmbeddingsClient(EmbeddingsClient):
+ def __init__(self):
+ self.client = OpenAI(
+ base_url=f"http://{config.ollama.host}:{config.ollama.port}/v1/",
+ api_key="ollama",
+ )
+ self.model = config.embeddings.local_model
+
+ def embed_text(self, text: str) -> list[float]:
+ response = self.client.embeddings.create(model=self.model, input=text)
+ return response.data[0].embedding
+
+ def embed_texts(self, texts: list[str]) -> list[list[float]]:
+ response = self.client.embeddings.create(model=self.model, input=texts)
+ sorted_data = sorted(response.data, key=lambda item: item.index)
+ return [item.embedding for item in sorted_data]
+
+
+_embeddings_ollama_client = OllamaEmbeddingsClient()
diff --git a/src/lib/embeddings/client_openai.py b/src/lib/embeddings/client_openai.py
new file mode 100644
index 0000000..c0df9d4
--- /dev/null
+++ b/src/lib/embeddings/client_openai.py
@@ -0,0 +1,95 @@
+import os
+import threading
+from typing import Any
+
+from openai import APIConnectionError, APITimeoutError, OpenAI
+from tenacity import (
+ retry,
+ retry_if_exception_type,
+ stop_after_attempt,
+ wait_exponential,
+ RetryError,
+)
+
+from src.adapters.interfaces.embeddings import EmbeddingsClient
+from src.config import config
+from src.lib.embeddings.client import EmbeddingError
+
+
+def _openai_client_kwargs() -> dict[str, Any]:
+ kwargs: dict[str, Any] = {
+ "api_key": config.openai.api_key,
+ "timeout": 60.0,
+ "max_retries": 3,
+ }
+ if config.openai.base_url:
+ kwargs["base_url"] = config.openai.base_url
+ return kwargs
+
+
+class OpenAIEmbeddingsClient(EmbeddingsClient):
+ def __init__(self):
+ self._client: OpenAI | None = None
+ self._lock = threading.Lock()
+ self._pid = os.getpid()
+ self.model = config.openai.embedding_model
+
+ def _check_fork(self) -> None:
+ if os.getpid() != self._pid:
+ self._client = None
+ self._pid = os.getpid()
+
+ @property
+ def client(self) -> OpenAI:
+ self._check_fork()
+ if self._client is None:
+ with self._lock:
+ if self._client is None:
+ self._client = OpenAI(**_openai_client_kwargs())
+ return self._client
+
+ @retry(
+ stop=stop_after_attempt(5),
+ wait=wait_exponential(multiplier=1, min=2, max=30),
+ retry=retry_if_exception_type((APIConnectionError, APITimeoutError)),
+ reraise=True,
+ )
+ def _embed_text_with_retry(self, text: str) -> list[float]:
+ response = self.client.embeddings.create(model=self.model, input=text)
+ return response.data[0].embedding
+
+ @retry(
+ stop=stop_after_attempt(5),
+ wait=wait_exponential(multiplier=1, min=2, max=30),
+ retry=retry_if_exception_type((APIConnectionError, APITimeoutError)),
+ reraise=True,
+ )
+ def _embed_texts_with_retry(self, texts: list[str]) -> list[list[float]]:
+ response = self.client.embeddings.create(model=self.model, input=texts)
+ sorted_data = sorted(response.data, key=lambda item: item.index)
+ return [item.embedding for item in sorted_data]
+
+ def embed_text(self, text: str) -> list[float]:
+ try:
+ return self._embed_text_with_retry(text)
+ except RetryError as e:
+ last = e.last_attempt.exception()
+ raise EmbeddingError(
+ f"OpenAI embedding failed after retries: {last}"
+ ) from last
+ except (APIConnectionError, APITimeoutError) as e:
+ raise EmbeddingError(f"OpenAI embedding connection error: {e}") from e
+
+ def embed_texts(self, texts: list[str]) -> list[list[float]]:
+ try:
+ return self._embed_texts_with_retry(texts)
+ except RetryError as e:
+ last = e.last_attempt.exception()
+ raise EmbeddingError(
+ f"OpenAI embedding failed after retries: {last}"
+ ) from last
+ except (APIConnectionError, APITimeoutError) as e:
+ raise EmbeddingError(f"OpenAI embedding connection error: {e}") from e
+
+
+_embeddings_openai_client = OpenAIEmbeddingsClient()
diff --git a/src/lib/embeddings/client_vertex.py b/src/lib/embeddings/client_vertex.py
new file mode 100644
index 0000000..1410877
--- /dev/null
+++ b/src/lib/embeddings/client_vertex.py
@@ -0,0 +1,29 @@
+import os
+
+from google import genai
+
+from src.adapters.interfaces.embeddings import EmbeddingsClient
+from src.config import config
+
+
+class VertexEmbeddingsClient(EmbeddingsClient):
+ def __init__(self):
+ os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = config.gcp.credentials_path
+ self.client = genai.Client(
+ vertexai=True,
+ project=config.gcp.project_id,
+ location="global",
+ http_options={"api_version": "v1"},
+ )
+ self.model = config.gcp.embedding_model
+
+ def embed_text(self, text: str) -> list[float]:
+ response = self.client.models.embed_content(model=self.model, contents=[text])
+ return response.embeddings[0].values
+
+ def embed_texts(self, texts: list[str]) -> list[list[float]]:
+ response = self.client.models.embed_content(model=self.model, contents=texts)
+ return [item.values for item in response.embeddings]
+
+
+_embeddings_vertex_client = VertexEmbeddingsClient()
diff --git a/src/lib/llm/client_azure.py b/src/lib/llm/client_azure.py
new file mode 100644
index 0000000..cb0ea70
--- /dev/null
+++ b/src/lib/llm/client_azure.py
@@ -0,0 +1,67 @@
+import json
+
+from langchain_openai import AzureChatOpenAI
+from openai import AzureOpenAI
+
+from src.adapters.interfaces.llm import LLM
+from src.config import config
+
+
+class _AzureLLMBase(LLM):
+ def __init__(self, model: str):
+ self.model = model
+ self.client = AzureOpenAI(
+ api_version=config.azure.llm_api_version,
+ azure_endpoint=config.azure.llm_endpoint,
+ api_key=config.azure.llm_subscription_key,
+ )
+ self.langchain_model = AzureChatOpenAI(
+ azure_deployment=model,
+ api_version=config.azure.llm_api_version,
+ azure_endpoint=config.azure.llm_endpoint,
+ api_key=config.azure.llm_subscription_key,
+ )
+
+ def generate_text(self, prompt: str, max_new_tokens: int = None) -> str:
+ response = self.client.chat.completions.create(
+ model=self.model,
+ messages=[{"role": "user", "content": prompt}],
+ **({"max_tokens": max_new_tokens} if max_new_tokens else {}),
+ )
+ return response.choices[0].message.content
+
+ def generate_json(
+ self, prompt: str, max_new_tokens: int = None, max_retries: int = 3
+ ) -> dict:
+ response = None
+ while max_retries > 0 and response is None:
+ try:
+ _response = self.client.chat.completions.create(
+ model=self.model,
+ messages=[{"role": "user", "content": prompt}],
+ **({"max_tokens": max_new_tokens} if max_new_tokens else {}),
+ response_format={"type": "json_object"},
+ )
+ _response = (
+ _response.choices[0].message.content.strip("```json").strip("```")
+ )
+ response = json.loads(_response)
+ except Exception as e:
+ max_retries -= 1
+ if max_retries <= 0:
+ raise e
+ return response
+
+
+class AzureLLMClientSmall(_AzureLLMBase):
+ def __init__(self):
+ super().__init__(config.azure.small_llm_model)
+
+
+class AzureLLMClientLarge(_AzureLLMBase):
+ def __init__(self):
+ super().__init__(config.azure.large_llm_model)
+
+
+_llm_small_client_azure = AzureLLMClientSmall()
+_llm_large_client_azure = AzureLLMClientLarge()
diff --git a/src/lib/llm/client_bedrock.py b/src/lib/llm/client_bedrock.py
new file mode 100644
index 0000000..b31628f
--- /dev/null
+++ b/src/lib/llm/client_bedrock.py
@@ -0,0 +1,69 @@
+import json
+
+import boto3
+from langchain_aws import ChatBedrockConverse
+
+from src.adapters.interfaces.llm import LLM
+from src.config import config
+
+
+class _BedrockLLMBase(LLM):
+ def __init__(self, model: str):
+ self.model = model
+ session = boto3.Session(
+ aws_access_key_id=config.bedrock.access_key_id,
+ aws_secret_access_key=config.bedrock.secret_access_key,
+ aws_session_token=config.bedrock.session_token,
+ region_name=config.bedrock.region,
+ )
+ self.client = session.client("bedrock-runtime")
+ self.langchain_model = ChatBedrockConverse(
+ model=model,
+ region_name=config.bedrock.region,
+ aws_access_key_id=config.bedrock.access_key_id,
+ aws_secret_access_key=config.bedrock.secret_access_key,
+ aws_session_token=config.bedrock.session_token,
+ )
+
+ def _converse(self, prompt: str, max_new_tokens: int = None) -> str:
+ payload = {
+ "modelId": self.model,
+ "messages": [{"role": "user", "content": [{"text": prompt}]}],
+ }
+ if max_new_tokens:
+ payload["inferenceConfig"] = {"maxTokens": max_new_tokens}
+ response = self.client.converse(**payload)
+ content = response["output"]["message"]["content"]
+ texts = [part.get("text", "") for part in content if isinstance(part, dict)]
+ return "".join(texts).strip()
+
+ def generate_text(self, prompt: str, max_new_tokens: int = None) -> str:
+ return self._converse(prompt, max_new_tokens=max_new_tokens)
+
+ def generate_json(
+ self, prompt: str, max_new_tokens: int = None, max_retries: int = 3
+ ) -> dict:
+ while max_retries > 0:
+ try:
+ response = self._converse(prompt, max_new_tokens=max_new_tokens)
+ raw = response.strip().strip("```json").strip("```").strip()
+ return json.loads(raw)
+ except Exception:
+ max_retries -= 1
+ if max_retries <= 0:
+ raise
+ return {}
+
+
+class BedrockLLMClientSmall(_BedrockLLMBase):
+ def __init__(self):
+ super().__init__(config.bedrock.small_llm_model)
+
+
+class BedrockLLMClientLarge(_BedrockLLMBase):
+ def __init__(self):
+ super().__init__(config.bedrock.large_llm_model)
+
+
+_llm_small_client_bedrock = BedrockLLMClientSmall()
+_llm_large_client_bedrock = BedrockLLMClientLarge()
diff --git a/src/lib/llm/client_large.py b/src/lib/llm/client_large.py
index fd080e7..3e1c63f 100644
--- a/src/lib/llm/client_large.py
+++ b/src/lib/llm/client_large.py
@@ -26,16 +26,16 @@ class LLMClientLarge(LLM):
def __init__(self):
self.model = config.azure.large_llm_model
self.client = AzureOpenAI(
- api_version=config.azure.large_llm_api_version,
- azure_endpoint=config.azure.large_llm_endpoint,
- api_key=config.azure.large_llm_subscription_key,
+ api_version=config.azure.llm_api_version,
+ azure_endpoint=config.azure.llm_endpoint,
+ api_key=config.azure.llm_subscription_key,
)
self.langchain_model = AzureChatOpenAI(
azure_deployment=config.azure.large_llm_model,
- api_version=config.azure.large_llm_api_version,
- azure_endpoint=config.azure.large_llm_endpoint,
- api_key=config.azure.large_llm_subscription_key,
+ api_version=config.azure.llm_api_version,
+ azure_endpoint=config.azure.llm_endpoint,
+ api_key=config.azure.llm_subscription_key,
)
def generate_text(self, prompt: str, max_new_tokens: int = None) -> str:
diff --git a/src/lib/llm/client_openai.py b/src/lib/llm/client_openai.py
new file mode 100644
index 0000000..9ab5dc8
--- /dev/null
+++ b/src/lib/llm/client_openai.py
@@ -0,0 +1,100 @@
+import json
+import os
+import threading
+from typing import Any
+
+from langchain_openai import ChatOpenAI
+from openai import OpenAI
+
+from src.adapters.interfaces.llm import LLM
+from src.config import config
+
+
+def _openai_client_kwargs() -> dict[str, Any]:
+ kwargs: dict[str, Any] = {
+ "api_key": config.openai.api_key,
+ "timeout": 120.0,
+ "max_retries": 3,
+ }
+ if config.openai.base_url:
+ kwargs["base_url"] = config.openai.base_url
+ return kwargs
+
+
+class _OpenAILLMBase(LLM):
+ def __init__(self, model: str):
+ self.model = model
+ self._client: OpenAI | None = None
+ self._langchain_model: ChatOpenAI | None = None
+ self._lock = threading.Lock()
+ self._pid = os.getpid()
+
+ def _check_fork(self) -> None:
+ if os.getpid() != self._pid:
+ self._client = None
+ self._langchain_model = None
+ self._pid = os.getpid()
+
+ @property
+ def client(self) -> OpenAI:
+ self._check_fork()
+ if self._client is None:
+ with self._lock:
+ if self._client is None:
+ self._client = OpenAI(**_openai_client_kwargs())
+ return self._client
+
+ @property
+ def langchain_model(self) -> ChatOpenAI:
+ self._check_fork()
+ if self._langchain_model is None:
+ with self._lock:
+ if self._langchain_model is None:
+ self._langchain_model = ChatOpenAI(
+ model=self.model, **_openai_client_kwargs()
+ )
+ return self._langchain_model
+
+ def generate_text(self, prompt: str, max_new_tokens: int = None) -> str:
+ response = self.client.chat.completions.create(
+ model=self.model,
+ messages=[{"role": "user", "content": prompt}],
+ **({"max_tokens": max_new_tokens} if max_new_tokens else {}),
+ )
+ return response.choices[0].message.content
+
+ def generate_json(
+ self, prompt: str, max_new_tokens: int = None, max_retries: int = 3
+ ) -> dict:
+ response = None
+ while max_retries > 0 and response is None:
+ try:
+ _response = self.client.chat.completions.create(
+ model=self.model,
+ messages=[{"role": "user", "content": prompt}],
+ **({"max_tokens": max_new_tokens} if max_new_tokens else {}),
+ response_format={"type": "json_object"},
+ )
+ _response = (
+ _response.choices[0].message.content.strip("```json").strip("```")
+ )
+ response = json.loads(_response)
+ except Exception as e:
+ max_retries -= 1
+ if max_retries <= 0:
+ raise e
+ return response
+
+
+class OpenAILLMClientSmall(_OpenAILLMBase):
+ def __init__(self):
+ super().__init__(config.openai.small_llm_model)
+
+
+class OpenAILLMClientLarge(_OpenAILLMBase):
+ def __init__(self):
+ super().__init__(config.openai.large_llm_model)
+
+
+_llm_small_client_openai = OpenAILLMClientSmall()
+_llm_large_client_openai = OpenAILLMClientLarge()
diff --git a/src/lib/llm/client_vertex.py b/src/lib/llm/client_vertex.py
new file mode 100644
index 0000000..1005b19
--- /dev/null
+++ b/src/lib/llm/client_vertex.py
@@ -0,0 +1,75 @@
+import json
+import os
+
+from langchain_google_vertexai import ChatVertexAI
+from google import genai
+from google.genai.types import GenerateContentConfig
+
+from src.adapters.interfaces.llm import LLM
+from src.config import config
+
+
+class _VertexLLMBase(LLM):
+ def __init__(self, model: str):
+ self.model = model
+ os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = config.gcp.credentials_path
+ self.client = genai.Client(
+ vertexai=True,
+ project=config.gcp.project_id,
+ location="global",
+ http_options={"api_version": "v1"},
+ )
+ self.langchain_model = ChatVertexAI(
+ model_name=model,
+ project=config.gcp.project_id,
+ location="global",
+ max_retries=5,
+ request_timeout=120,
+ streaming=False,
+ )
+
+ def generate_text(self, prompt: str, max_new_tokens: int = None) -> str:
+ response = self.client.models.generate_content(
+ model=self.model,
+ contents=[prompt],
+ config=GenerateContentConfig(
+ response_mime_type="text/plain",
+ **({"max_output_tokens": max_new_tokens} if max_new_tokens else {}),
+ ),
+ )
+ return response.text
+
+ def generate_json(
+ self, prompt: str, max_new_tokens: int = None, max_retries: int = 3
+ ) -> dict:
+ while max_retries > 0:
+ try:
+ response = self.client.models.generate_content(
+ model=self.model,
+ contents=[prompt],
+ config=GenerateContentConfig(
+ response_mime_type="application/json",
+ **({"max_output_tokens": max_new_tokens} if max_new_tokens else {}),
+ ),
+ )
+ raw = response.text.strip().strip("```json").strip("```").strip()
+ return json.loads(raw)
+ except Exception:
+ max_retries -= 1
+ if max_retries <= 0:
+ raise
+ return {}
+
+
+class VertexLLMClientSmall(_VertexLLMBase):
+ def __init__(self):
+ super().__init__(config.gcp.small_llm_model)
+
+
+class VertexLLMClientLarge(_VertexLLMBase):
+ def __init__(self):
+ super().__init__(config.gcp.large_llm_model)
+
+
+_llm_small_client_vertex = VertexLLMClientSmall()
+_llm_large_client_vertex = VertexLLMClientLarge()
diff --git a/src/lib/postgresql/__init__.py b/src/lib/postgresql/__init__.py
new file mode 100644
index 0000000..406a21a
--- /dev/null
+++ b/src/lib/postgresql/__init__.py
@@ -0,0 +1,28 @@
+"""
+File: /__init__.py
+Project: postgresql
+Created Date: Sunday May 24th 2026
+Author: Christian Nonis <[email protected]>
+"""
+
+from src.lib.postgresql.data import (
+ PostgreSQLDataClient,
+ get_postgresql_data_client,
+)
+from src.lib.postgresql.networkx import (
+ NetworkXGraphClient,
+ get_networkx_graph_client,
+)
+from src.lib.postgresql.vectors import (
+ PostgreSQLVectorStoreClient,
+ get_postgresql_vector_store_client,
+)
+
+__all__ = [
+ "NetworkXGraphClient",
+ "get_networkx_graph_client",
+ "PostgreSQLVectorStoreClient",
+ "get_postgresql_vector_store_client",
+ "PostgreSQLDataClient",
+ "get_postgresql_data_client",
+]
diff --git a/src/lib/postgresql/_naming.py b/src/lib/postgresql/_naming.py
new file mode 100644
index 0000000..8053d1e
--- /dev/null
+++ b/src/lib/postgresql/_naming.py
@@ -0,0 +1,49 @@
+"""
+File: /_naming.py
+Project: postgresql
+
+Helpers for converting a `brain_id` (which can be a UUID, name_key, or any
+arbitrary string) into a deterministic Postgres-safe database identifier.
+
+Postgres identifiers must be at most 63 bytes (NAMEDATALEN - 1) and, when
+unquoted, can only contain `[a-z][a-z0-9_]*`. We always lowercase + sanitize
+to ASCII `[a-z0-9_]`. If the resulting name exceeds the length budget we
+truncate the human-readable tail and append a SHA-256 prefix so the mapping
+stays stable and collision-resistant.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+__all__ = ["brain_db_name", "BRAIN_DB_PREFIX"]
+
+
+BRAIN_DB_PREFIX = "brain_"
+_MAX_DBNAME_LEN = 63
+_HASH_SUFFIX_LEN = 12
+
+_SANITIZE_RE = re.compile(r"[^a-z0-9_]+")
+
+
+def brain_db_name(brain_id: str) -> str:
+ """Return the Postgres database name that hosts `brain_id`.
+
+ Always lowercase, ASCII, and stable across runs for the same `brain_id`.
+ """
+ if not brain_id:
+ raise ValueError("brain_id must be a non-empty string")
+
+ sanitized = _SANITIZE_RE.sub("_", brain_id.lower()).strip("_")
+ if not sanitized:
+ sanitized = "x"
+
+ candidate = f"{BRAIN_DB_PREFIX}{sanitized}"
+ if len(candidate) <= _MAX_DBNAME_LEN:
+ return candidate
+
+ digest = hashlib.sha256(brain_id.encode("utf-8")).hexdigest()[:_HASH_SUFFIX_LEN]
+ head_budget = _MAX_DBNAME_LEN - len(BRAIN_DB_PREFIX) - len(digest) - 1
+ head = sanitized[:head_budget].rstrip("_")
+ return f"{BRAIN_DB_PREFIX}{head}_{digest}"
diff --git a/src/lib/postgresql/_provisioning.py b/src/lib/postgresql/_provisioning.py
new file mode 100644
index 0000000..20d6f3f
--- /dev/null
+++ b/src/lib/postgresql/_provisioning.py
@@ -0,0 +1,190 @@
+"""
+File: /_provisioning.py
+Project: postgresql
+
+Process-wide Postgres infrastructure shared by the data / vectors / networkx
+clients:
+
+ * `get_pool(dbname)` — LRU cache of psycopg2 ThreadedConnectionPools.
+ Fork-safe (resets on child process).
+ * `get_system_pool()` — convenience helper for the registry DB
+ (config.postgresql.system_database).
+ * `get_brain_pool(brain_id)` — convenience helper for the per-brain DB,
+ resolved through `_naming.brain_db_name`.
+ * `ensure_brain_database(brain_id)` — `CREATE DATABASE brain_<id>` if missing,
+ executed against the maintenance database
+ (default `postgres`).
+
+Each brain gets its own Postgres database. The LRU keeps at most
+`_MAX_OPEN_POOLS` pools warm; older pools are closed to bound Postgres's
+`max_connections` footprint when there are many brains.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from collections import OrderedDict
+from contextlib import contextmanager
+from typing import Iterator, Optional
+
+import psycopg2
+import psycopg2.errors
+import psycopg2.pool
+from psycopg2 import sql
+
+from src.config import config
+
+from ._naming import brain_db_name
+
+logger = logging.getLogger(__name__)
+
+
+_MAX_OPEN_POOLS = 16
+_DEFAULT_MIN_CONN = 1
+_DEFAULT_MAX_CONN = 4
+_MAINTENANCE_FALLBACK_DB = "postgres"
+
+
+def _maintenance_dbname() -> str:
+ return getattr(config.postgresql, "maintenance_database", None) or _MAINTENANCE_FALLBACK_DB
+
+
+def _system_dbname() -> str:
+ return getattr(config.postgresql, "system_database", None) or config.postgresql.database
+
+
+class _PoolRegistry:
+ def __init__(self) -> None:
+ self._pools: "OrderedDict[str, psycopg2.pool.ThreadedConnectionPool]" = OrderedDict()
+ self._lock = threading.RLock()
+ self._pid: Optional[int] = None
+
+ def _reset_if_forked(self) -> None:
+ current = os.getpid()
+ if self._pid is not None and self._pid != current:
+ for name, pool in list(self._pools.items()):
+ try:
+ pool.closeall()
+ except Exception as exc:
+ logger.debug("Failed to close pool %s on fork: %s", name, exc)
+ self._pools.clear()
+ self._pid = current
+
+ def get(
+ self,
+ dbname: str,
+ minconn: int = _DEFAULT_MIN_CONN,
+ maxconn: int = _DEFAULT_MAX_CONN,
+ ) -> psycopg2.pool.ThreadedConnectionPool:
+ with self._lock:
+ self._reset_if_forked()
+ existing = self._pools.get(dbname)
+ if existing is not None:
+ self._pools.move_to_end(dbname)
+ return existing
+
+ config.postgresql.validate_credentials()
+ pool = psycopg2.pool.ThreadedConnectionPool(
+ minconn=minconn,
+ maxconn=maxconn,
+ host=config.postgresql.host,
+ port=config.postgresql.port,
+ user=config.postgresql.username,
+ password=config.postgresql.password,
+ dbname=dbname,
+ )
+ self._pools[dbname] = pool
+ self._evict_if_needed()
+ return pool
+
+ def _evict_if_needed(self) -> None:
+ while len(self._pools) > _MAX_OPEN_POOLS:
+ evicted_name, evicted_pool = self._pools.popitem(last=False)
+ try:
+ evicted_pool.closeall()
+ except Exception as exc:
+ logger.warning("Failed to close LRU pool %s: %s", evicted_name, exc)
+ else:
+ logger.debug("Evicted LRU pool: %s", evicted_name)
+
+
+_registry = _PoolRegistry()
+
+
+def get_pool(dbname: str, **kwargs) -> psycopg2.pool.ThreadedConnectionPool:
+ return _registry.get(dbname, **kwargs)
+
+
+def get_system_pool() -> psycopg2.pool.ThreadedConnectionPool:
+ return _registry.get(_system_dbname())
+
+
+def get_brain_pool(brain_id: str) -> psycopg2.pool.ThreadedConnectionPool:
+ return _registry.get(brain_db_name(brain_id))
+
+
+@contextmanager
+def borrow(pool: psycopg2.pool.ThreadedConnectionPool) -> Iterator[psycopg2.extensions.connection]:
+ conn = pool.getconn()
+ try:
+ yield conn
+ finally:
+ pool.putconn(conn)
+
+
+_created_dbs: set[str] = set()
+_create_lock = threading.Lock()
+
+
+def ensure_database_exists(dbname: str) -> None:
+ """Create `dbname` if it does not yet exist on the cluster.
+
+ Idempotent and safe under concurrent callers. Uses the maintenance database
+ (typically `postgres`) for the CREATE DATABASE statement and records a
+ process-local cache so future calls become free.
+ """
+ if dbname in _created_dbs:
+ return
+ with _create_lock:
+ if dbname in _created_dbs:
+ return
+ conn = psycopg2.connect(
+ host=config.postgresql.host,
+ port=config.postgresql.port,
+ user=config.postgresql.username,
+ password=config.postgresql.password,
+ dbname=_maintenance_dbname(),
+ )
+ try:
+ conn.autocommit = True
+ with conn.cursor() as cur:
+ cur.execute(
+ "SELECT 1 FROM pg_database WHERE datname = %s",
+ (dbname,),
+ )
+ if cur.fetchone() is None:
+ try:
+ cur.execute(
+ sql.SQL("CREATE DATABASE {}").format(sql.Identifier(dbname))
+ )
+ logger.info("Created Postgres database: %s", dbname)
+ except psycopg2.errors.DuplicateDatabase:
+ pass
+ finally:
+ conn.close()
+ _created_dbs.add(dbname)
+
+
+def ensure_brain_database(brain_id: str) -> str:
+ """Return the per-brain database name, creating the database if needed."""
+ dbname = brain_db_name(brain_id)
+ ensure_database_exists(dbname)
+ return dbname
+
+
+def ensure_system_database() -> str:
+ dbname = _system_dbname()
+ ensure_database_exists(dbname)
+ return dbname
diff --git a/src/lib/postgresql/data.py b/src/lib/postgresql/data.py
new file mode 100644
index 0000000..d16caee
--- /dev/null
+++ b/src/lib/postgresql/data.py
@@ -0,0 +1,713 @@
+"""
+File: /data.py
+Project: postgresql
+Created Date: Sunday May 24th 2026
+Author: Christian Nonis <[email protected]>
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import json
+import threading
+from typing import Any, Iterator, List, Optional, Tuple
+
+import psycopg2
+import psycopg2.extras
+
+from src.adapters.interfaces.data import DataClient, SearchResult
+from src.config import config
+from src.constants.data import (
+ Brain,
+ KGChanges,
+ KGChangesType,
+ Observation,
+ StructuredData,
+ TextChunk,
+)
+
+from ._provisioning import (
+ borrow,
+ ensure_brain_database,
+ ensure_database_exists,
+ get_brain_pool,
+ get_system_pool,
+)
+
+
+_SYSTEM_DDL = """
+CREATE TABLE IF NOT EXISTS data_brains (
+ id TEXT PRIMARY KEY,
+ name_key TEXT UNIQUE NOT NULL,
+ pat TEXT NOT NULL,
+ document JSONB NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+"""
+
+
+_BRAIN_DDL = """
+CREATE TABLE IF NOT EXISTS data_text_chunks (
+ id TEXT PRIMARY KEY,
+ text TEXT,
+ metadata JSONB,
+ inserted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ document JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_data_text_chunks_inserted_at
+ ON data_text_chunks (inserted_at DESC);
+
+CREATE TABLE IF NOT EXISTS data_observations (
+ id TEXT PRIMARY KEY,
+ text TEXT,
+ resource_id TEXT,
+ metadata JSONB,
+ inserted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ document JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_data_observations_resource
+ ON data_observations (resource_id);
+CREATE INDEX IF NOT EXISTS idx_data_observations_labels
+ ON data_observations USING gin ((metadata -> 'labels'));
+
+CREATE TABLE IF NOT EXISTS data_structured_data (
+ id TEXT PRIMARY KEY,
+ data JSONB,
+ types TEXT[],
+ metadata JSONB,
+ inserted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ document JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_data_structured_data_types
+ ON data_structured_data USING gin (types);
+CREATE INDEX IF NOT EXISTS idx_data_structured_data_inserted_at
+ ON data_structured_data (inserted_at DESC);
+
+CREATE TABLE IF NOT EXISTS data_kg_changes (
+ id TEXT PRIMARY KEY,
+ type TEXT,
+ change JSONB,
+ timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ document JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_data_kg_changes_timestamp
+ ON data_kg_changes (timestamp DESC);
+"""
+
+
+def _ilike_pattern(query_text: str) -> str:
+ escaped = query_text.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+ return f"%{escaped}%"
+
+
+def _validate_changelog(document: dict) -> Optional[KGChanges]:
+ if "change" in document and isinstance(document["change"], dict):
+ change_type = document["change"].get("type")
+ if isinstance(change_type, str):
+ document["change"]["type"] = KGChangesType(change_type)
+ if isinstance(document.get("type"), str):
+ document["type"] = KGChangesType(document["type"])
+ return KGChanges.model_validate(document)
+
+
+class PostgreSQLDataClient(DataClient):
+ """
+ Data client backed by PostgreSQL with JSONB-stored documents.
+
+ Mirrors the Mongo client's `database = brain_id` layout: a single registry
+ database (``config.postgresql.system_database``) holds the ``data_brains``
+ catalog, and every brain owns its own Postgres database (named
+ ``brain_<sanitized_id>``) containing all of its tables.
+ """
+
+ def __init__(self):
+ self._lock = threading.Lock()
+ self._system_initialized = False
+ self._initialized_brains: set[str] = set()
+
+ @contextmanager
+ def _system_connection(self) -> Iterator[psycopg2.extensions.connection]:
+ self._ensure_system_schema()
+ with borrow(get_system_pool()) as conn:
+ yield conn
+
+ @contextmanager
+ def _brain_connection(
+ self, brain_id: str
+ ) -> Iterator[psycopg2.extensions.connection]:
+ self._ensure_brain_schema(brain_id)
+ with borrow(get_brain_pool(brain_id)) as conn:
+ yield conn
+
+ def _ensure_system_schema(self) -> None:
+ if self._system_initialized:
+ return
+ with self._lock:
+ if self._system_initialized:
+ return
+ ensure_database_exists(config.postgresql.system_database)
+ with borrow(get_system_pool()) as conn:
+ with conn.cursor() as cur:
+ cur.execute(_SYSTEM_DDL)
+ conn.commit()
+ self._system_initialized = True
+
+ def _ensure_brain_schema(self, brain_id: str) -> None:
+ if brain_id in self._initialized_brains:
+ return
+ with self._lock:
+ if brain_id in self._initialized_brains:
+ return
+ ensure_brain_database(brain_id)
+ with borrow(get_brain_pool(brain_id)) as conn:
+ with conn.cursor() as cur:
+ cur.execute(_BRAIN_DDL)
+ conn.commit()
+ self._initialized_brains.add(brain_id)
+
+ def save_text_chunk(self, text_chunk: TextChunk, brain_id: str) -> TextChunk:
+ document = text_chunk.model_dump(mode="json")
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ INSERT INTO data_text_chunks
+ (id, text, metadata, inserted_at, document)
+ VALUES (%s, %s, %s::jsonb, %s, %s::jsonb)
+ ON CONFLICT (id) DO UPDATE SET
+ text = EXCLUDED.text,
+ metadata = EXCLUDED.metadata,
+ inserted_at = EXCLUDED.inserted_at,
+ document = EXCLUDED.document
+ """,
+ (
+ text_chunk.id,
+ text_chunk.text,
+ json.dumps(text_chunk.metadata or {}, default=str),
+ text_chunk.inserted_at,
+ json.dumps(document, default=str),
+ ),
+ )
+ conn.commit()
+ return text_chunk
+
+ def save_observations(
+ self, observations: List[Observation], brain_id: str
+ ) -> List[Observation]:
+ if not observations:
+ return observations
+ rows = [
+ (
+ observation.id,
+ observation.text,
+ observation.resource_id,
+ json.dumps(observation.metadata or {}, default=str),
+ observation.inserted_at,
+ json.dumps(observation.model_dump(mode="json"), default=str),
+ )
+ for observation in observations
+ ]
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ psycopg2.extras.execute_values(
+ cur,
+ """
+ INSERT INTO data_observations
+ (id, text, resource_id, metadata, inserted_at, document)
+ VALUES %s
+ ON CONFLICT (id) DO UPDATE SET
+ text = EXCLUDED.text,
+ resource_id = EXCLUDED.resource_id,
+ metadata = EXCLUDED.metadata,
+ inserted_at = EXCLUDED.inserted_at,
+ document = EXCLUDED.document
+ """,
+ rows,
+ template="(%s, %s, %s, %s::jsonb, %s, %s::jsonb)",
+ )
+ conn.commit()
+ return observations
+
+ def search(
+ self,
+ text: str,
+ brain_id: str,
+ collection: str = "text_chunks",
+ limit: int = 10,
+ ) -> SearchResult:
+ table = (
+ "data_text_chunks"
+ if collection in ("*", "text_chunks")
+ else f"data_{collection}"
+ )
+ pattern = _ilike_pattern(text)
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT document
+ FROM {table}
+ WHERE text ILIKE %s
+ LIMIT %s
+ """,
+ (pattern, limit),
+ )
+ text_rows = cur.fetchall()
+ text_chunks = [
+ TextChunk.model_validate(row["document"]) for row in text_rows
+ ]
+ ids = [chunk.id for chunk in text_chunks]
+ observations: list[Observation] = []
+ if ids:
+ cur.execute(
+ """
+ SELECT document
+ FROM data_observations
+ WHERE resource_id = ANY(%s)
+ """,
+ (ids,),
+ )
+ observations = [
+ Observation.model_validate(row["document"])
+ for row in cur.fetchall()
+ ]
+ return SearchResult(text_chunks=text_chunks, observations=observations)
+
+ def get_text_chunks_by_ids(
+ self, ids: List[str], with_observations: bool = False, brain_id: str = "default"
+ ) -> Tuple[List[TextChunk], List[Observation]]:
+ if not ids:
+ return ([], [])
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ """
+ SELECT document FROM data_text_chunks
+ WHERE id = ANY(%s)
+ """,
+ (ids,),
+ )
+ text_chunks = [
+ TextChunk.model_validate(row["document"]) for row in cur.fetchall()
+ ]
+ observations: list[Observation] = []
+ if with_observations:
+ cur.execute(
+ """
+ SELECT document FROM data_observations
+ WHERE resource_id = ANY(%s)
+ """,
+ (ids,),
+ )
+ observations = [
+ Observation.model_validate(row["document"])
+ for row in cur.fetchall()
+ ]
+ return (text_chunks, observations)
+
+ def save_structured_data(
+ self, structured_data: StructuredData, brain_id: str
+ ) -> StructuredData:
+ document = structured_data.model_dump(mode="json")
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ INSERT INTO data_structured_data
+ (id, data, types, metadata, inserted_at, document)
+ VALUES (%s, %s::jsonb, %s, %s::jsonb, %s, %s::jsonb)
+ ON CONFLICT (id) DO UPDATE SET
+ data = EXCLUDED.data,
+ types = EXCLUDED.types,
+ metadata = EXCLUDED.metadata,
+ inserted_at = EXCLUDED.inserted_at,
+ document = EXCLUDED.document
+ """,
+ (
+ structured_data.id,
+ json.dumps(structured_data.data or {}, default=str),
+ list(structured_data.types or []),
+ json.dumps(structured_data.metadata or {}, default=str),
+ structured_data.inserted_at,
+ json.dumps(document, default=str),
+ ),
+ )
+ conn.commit()
+ return structured_data
+
+ def create_brain(self, name_key: str) -> Brain:
+ brain = Brain(name_key=name_key)
+ document = brain.model_dump(mode="json")
+ with self._system_connection() as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ INSERT INTO data_brains (id, name_key, pat, document)
+ VALUES (%s, %s, %s, %s::jsonb)
+ """,
+ (
+ brain.id,
+ brain.name_key,
+ brain.pat,
+ json.dumps(document, default=str),
+ ),
+ )
+ conn.commit()
+ self._ensure_brain_schema(brain.id)
+ return brain
+
+ def get_brain(self, name_key: str) -> Optional[Brain]:
+ with self._system_connection() as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ "SELECT document FROM data_brains WHERE name_key = %s",
+ (name_key,),
+ )
+ row = cur.fetchone()
+ if not row:
+ return None
+ return Brain.model_validate(row["document"])
+
+ def get_brains_list(self) -> List[Brain]:
+ with self._system_connection() as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute("SELECT document FROM data_brains")
+ rows = cur.fetchall()
+ return [Brain.model_validate(row["document"]) for row in rows]
+
+ def save_kg_changes(self, kg_changes: KGChanges, brain_id: str) -> KGChanges:
+ document = kg_changes.model_dump(mode="json")
+ type_value = (
+ kg_changes.type.value
+ if isinstance(kg_changes.type, KGChangesType)
+ else kg_changes.type
+ )
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ INSERT INTO data_kg_changes
+ (id, type, change, timestamp, document)
+ VALUES (%s, %s, %s::jsonb, %s, %s::jsonb)
+ ON CONFLICT (id) DO UPDATE SET
+ type = EXCLUDED.type,
+ change = EXCLUDED.change,
+ timestamp = EXCLUDED.timestamp,
+ document = EXCLUDED.document
+ """,
+ (
+ kg_changes.id,
+ type_value,
+ json.dumps(document.get("change") or {}, default=str),
+ kg_changes.timestamp,
+ json.dumps(document, default=str),
+ ),
+ )
+ conn.commit()
+ return kg_changes
+
+ def get_structured_data_by_id(
+ self, id: str, brain_id: str
+ ) -> Optional[StructuredData]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ """
+ SELECT document FROM data_structured_data
+ WHERE id = %s
+ """,
+ (id,),
+ )
+ row = cur.fetchone()
+ if not row:
+ return None
+ return StructuredData.model_validate(row["document"])
+
+ def get_structured_data_list(
+ self,
+ brain_id: str,
+ limit: int = 10,
+ skip: int = 0,
+ types: list[str] = None,
+ query_text: str = None,
+ ) -> Tuple[list[StructuredData], int]:
+ clauses: list[str] = []
+ params: list[Any] = []
+ if types:
+ clauses.append("types && %s")
+ params.append(list(types))
+ if query_text:
+ pattern = _ilike_pattern(query_text)
+ clauses.append(
+ "(data::text ILIKE %s OR metadata::text ILIKE %s "
+ "OR EXISTS (SELECT 1 FROM unnest(types) t WHERE t ILIKE %s))"
+ )
+ params.extend([pattern, pattern, pattern])
+ where_sql = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT document FROM data_structured_data
+ {where_sql}
+ ORDER BY inserted_at DESC
+ OFFSET %s LIMIT %s
+ """,
+ (*params, skip, limit),
+ )
+ rows = cur.fetchall()
+ cur.execute(
+ f"SELECT COUNT(*) AS total FROM data_structured_data {where_sql}",
+ tuple(params),
+ )
+ total = cur.fetchone()["total"]
+ return (
+ [StructuredData.model_validate(row["document"]) for row in rows],
+ int(total or 0),
+ )
+
+ def get_text_chunks(
+ self, brain_id: str, limit: int = 10, skip: int = 0, query_text: str = None
+ ) -> Tuple[List[TextChunk], int]:
+ clauses: list[str] = []
+ params: list[Any] = []
+ if query_text:
+ pattern = _ilike_pattern(query_text)
+ clauses.append("(text ILIKE %s OR metadata::text ILIKE %s)")
+ params.extend([pattern, pattern])
+ where_sql = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT document FROM data_text_chunks
+ {where_sql}
+ ORDER BY inserted_at DESC
+ OFFSET %s LIMIT %s
+ """,
+ (*params, skip, limit),
+ )
+ rows = cur.fetchall()
+ cur.execute(
+ f"SELECT COUNT(*) AS total FROM data_text_chunks {where_sql}",
+ tuple(params),
+ )
+ total = cur.fetchone()["total"]
+ return (
+ [TextChunk.model_validate(row["document"]) for row in rows],
+ int(total or 0),
+ )
+
+ def get_structured_data_types(self, brain_id: str) -> list[str]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ SELECT DISTINCT unnest(types) AS t
+ FROM data_structured_data
+ WHERE types IS NOT NULL
+ ORDER BY t
+ """
+ )
+ return [row[0] for row in cur.fetchall() if row[0] is not None]
+
+ def get_observation_by_id(self, id: str, brain_id: str) -> Optional[Observation]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ """
+ SELECT document FROM data_observations
+ WHERE id = %s
+ """,
+ (id,),
+ )
+ row = cur.fetchone()
+ if not row:
+ return None
+ return Observation.model_validate(row["document"])
+
+ def get_observations_list(
+ self,
+ brain_id: str,
+ limit: int = 10,
+ skip: int = 0,
+ resource_id: str = None,
+ labels: list[str] = None,
+ query_text: str = None,
+ ) -> list[Observation]:
+ clauses: list[str] = []
+ params: list[Any] = []
+ if resource_id:
+ clauses.append("resource_id = %s")
+ params.append(resource_id)
+ if labels:
+ clauses.append("metadata -> 'labels' ?| %s")
+ params.append(list(labels))
+ if query_text:
+ pattern = _ilike_pattern(query_text)
+ clauses.append(
+ "(text ILIKE %s OR resource_id ILIKE %s OR metadata::text ILIKE %s)"
+ )
+ params.extend([pattern, pattern, pattern])
+ where_sql = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT document FROM data_observations
+ {where_sql}
+ ORDER BY inserted_at DESC
+ OFFSET %s LIMIT %s
+ """,
+ (*params, skip, limit),
+ )
+ rows = cur.fetchall()
+ return [Observation.model_validate(row["document"]) for row in rows]
+
+ def get_observation_labels(self, brain_id: str) -> list[str]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ SELECT DISTINCT jsonb_array_elements_text(metadata -> 'labels') AS label
+ FROM data_observations
+ WHERE metadata ? 'labels'
+ AND jsonb_typeof(metadata -> 'labels') = 'array'
+ ORDER BY label
+ """
+ )
+ return [row[0] for row in cur.fetchall() if row[0] is not None]
+
+ def get_changelog_by_id(self, id: str, brain_id: str) -> Optional[KGChanges]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ """
+ SELECT document FROM data_kg_changes
+ WHERE id = %s
+ """,
+ (id,),
+ )
+ row = cur.fetchone()
+ if not row:
+ return None
+ return _validate_changelog(dict(row["document"]))
+
+ def get_changelogs_list(
+ self,
+ brain_id: str,
+ limit: int = 10,
+ skip: int = 0,
+ types: list[str] = None,
+ query_text: str = None,
+ ) -> list[KGChanges]:
+ clauses: list[str] = []
+ params: list[Any] = []
+ if types:
+ clauses.append("type = ANY(%s)")
+ params.append(list(types))
+ if query_text:
+ pattern = _ilike_pattern(query_text)
+ clauses.append("(change::text ILIKE %s OR type ILIKE %s)")
+ params.extend([pattern, pattern])
+ where_sql = f"WHERE {' AND '.join(clauses)}" if clauses else ""
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT document FROM data_kg_changes
+ {where_sql}
+ ORDER BY timestamp DESC
+ OFFSET %s LIMIT %s
+ """,
+ (*params, skip, limit),
+ )
+ rows = cur.fetchall()
+ changelogs: list[KGChanges] = []
+ for row in rows:
+ try:
+ changelogs.append(_validate_changelog(dict(row["document"])))
+ except Exception as exc:
+ print(f"Error parsing changelog {row['document'].get('id')}: {exc}")
+ continue
+ return changelogs
+
+ def get_changelog_types(self, brain_id: str) -> list[str]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ SELECT DISTINCT type FROM data_kg_changes
+ WHERE type IS NOT NULL
+ ORDER BY type
+ """
+ )
+ return [row[0] for row in cur.fetchall()]
+
+ def update_structured_data(
+ self, structured_data: StructuredData, brain_id: str
+ ) -> StructuredData:
+ document = structured_data.model_dump(mode="json")
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ UPDATE data_structured_data SET
+ data = %s::jsonb,
+ types = %s,
+ metadata = %s::jsonb,
+ inserted_at = %s,
+ document = %s::jsonb
+ WHERE id = %s
+ """,
+ (
+ json.dumps(structured_data.data or {}, default=str),
+ list(structured_data.types or []),
+ json.dumps(structured_data.metadata or {}, default=str),
+ structured_data.inserted_at,
+ json.dumps(document, default=str),
+ structured_data.id,
+ ),
+ )
+ conn.commit()
+ return structured_data
+
+ def get_last_text_chunks(self, brain_id: str, limit: int = 10) -> list[TextChunk]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ """
+ SELECT document FROM data_text_chunks
+ ORDER BY inserted_at DESC
+ LIMIT %s
+ """,
+ (limit,),
+ )
+ rows = cur.fetchall()
+ return [TextChunk.model_validate(row["document"]) for row in rows]
+
+ def get_last_structured_data(
+ self, brain_id: str, limit: int = 10
+ ) -> list[StructuredData]:
+ with self._brain_connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ """
+ SELECT document FROM data_structured_data
+ ORDER BY inserted_at DESC
+ LIMIT %s
+ """,
+ (limit,),
+ )
+ rows = cur.fetchall()
+ return [StructuredData.model_validate(row["document"]) for row in rows]
+
+
+_postgresql_data_client: Optional[PostgreSQLDataClient] = None
+
+
+def get_postgresql_data_client() -> PostgreSQLDataClient:
+ global _postgresql_data_client
+ if _postgresql_data_client is None:
+ _postgresql_data_client = PostgreSQLDataClient()
+ return _postgresql_data_client
diff --git a/src/lib/postgresql/docker-compose.yaml b/src/lib/postgresql/docker-compose.yaml
new file mode 100644
index 0000000..6d53f2a
--- /dev/null
+++ b/src/lib/postgresql/docker-compose.yaml
@@ -0,0 +1,39 @@
+services:
+ postgres:
+ image: pgvector/pgvector:pg16
+ container_name: postgres
+ restart: always
+ ports:
+ - "5432:5432"
+ environment:
+ POSTGRES_USER: postgres
+ POSTGRES_PASSWORD: password
+ volumes:
+ - postgres-data:/var/lib/postgresql/data
+ healthcheck:
+ test: ["CMD-SHELL", "pg_isready -U postgres -d brainapi"]
+ interval: 5s
+ timeout: 5s
+ retries: 10
+
+ pgadmin:
+ image: dpage/pgadmin4:latest
+ container_name: pgadmin
+ restart: always
+ ports:
+ - "8082:80"
+ environment:
+ PGADMIN_DEFAULT_EMAIL: [email protected]
+ PGADMIN_DEFAULT_PASSWORD: admin
+ PGADMIN_CONFIG_SERVER_MODE: "False"
+ volumes:
+ - pgadmin-data:/var/lib/pgadmin
+ depends_on:
+ postgres:
+ condition: service_healthy
+
+volumes:
+ postgres-data:
+ driver: local
+ pgadmin-data:
+ driver: local
diff --git a/src/lib/postgresql/graph_store.py b/src/lib/postgresql/graph_store.py
new file mode 100644
index 0000000..823be1d
--- /dev/null
+++ b/src/lib/postgresql/graph_store.py
@@ -0,0 +1,596 @@
+"""
+File: /graph_store.py
+Project: postgresql
+Created Date: Sunday May 24th 2026
+Author: Christian Nonis <[email protected]>
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import json
+import threading
+from typing import Any, Dict, List, Optional
+
+import networkx as nx
+import psycopg2
+import psycopg2.extras
+
+from src.config import config
+
+from ._provisioning import borrow, ensure_brain_database, get_brain_pool
+
+
+class GraphDatabaseError(Exception):
+ code: Optional[str] = None
+
+ def __init__(self, message: str, code: Optional[str] = None):
+ super().__init__(message)
+ self.code = code
+
+
+class _NodeProxy(dict):
+ def get(self, key: str, default: Any = None) -> Any:
+ return super().get(key, default)
+
+ @property
+ def element_id(self) -> str:
+ return str(self.get("uuid", ""))
+
+
+class _RelationshipProxy(dict):
+ def __init__(self, data: dict, start: _NodeProxy, end: _NodeProxy):
+ super().__init__(data)
+ self._start = start
+ self._end = end
+ self.type = data.get("rel_type") or data.get("type") or ""
+
+ @property
+ def start_node(self) -> _NodeProxy:
+ return self._start
+
+ @property
+ def end_node(self) -> _NodeProxy:
+ return self._end
+
+ @property
+ def nodes(self) -> list:
+ return [self._start, self._end]
+
+
+class _BrainGraph:
+ def __init__(self, brain_id: str):
+ self.brain_id = brain_id
+ self.graph = nx.MultiDiGraph()
+
+ def node_data(self, uuid: str) -> dict:
+ return dict(self.graph.nodes[uuid])
+
+ def labels(self, uuid: str) -> list[str]:
+ return list(self.node_data(uuid).get("labels") or [])
+
+ def upsert_node(self, labels: list[str], identification: dict, properties: dict) -> str:
+ node_uuid = properties.get("uuid") or identification.get("uuid")
+ match_uuid = None
+ for candidate_uuid, data in self.graph.nodes(data=True):
+ if identification.get("uuid") and candidate_uuid != identification["uuid"]:
+ continue
+ if identification.get("name") and data.get("name") != identification.get("name"):
+ continue
+ if labels and not set(labels).issubset(set(data.get("labels") or [])):
+ continue
+ extra_match = True
+ for key, value in identification.items():
+ if key in {"uuid", "name"}:
+ continue
+ if data.get(key) != value:
+ extra_match = False
+ break
+ if extra_match:
+ match_uuid = candidate_uuid
+ break
+ if match_uuid is None:
+ match_uuid = node_uuid or identification.get("uuid")
+ if match_uuid is None:
+ raise ValueError("Unable to resolve node uuid for merge")
+ merged = {}
+ if match_uuid in self.graph:
+ merged.update(self.node_data(match_uuid))
+ merged.update(properties)
+ merged["labels"] = labels or merged.get("labels") or []
+ merged["uuid"] = match_uuid
+ merged.setdefault("name", identification.get("name"))
+ self.graph.add_node(match_uuid, **merged)
+ return match_uuid
+
+ def find_nodes(
+ self,
+ labels: Optional[list[str]] = None,
+ filters: Optional[dict[str, Any]] = None,
+ ) -> list[str]:
+ results: list[str] = []
+ for uuid, data in self.graph.nodes(data=True):
+ if labels and not set(labels).issubset(set(data.get("labels") or [])):
+ continue
+ if filters:
+ matched = True
+ for key, value in filters.items():
+ if data.get(key) != value:
+ matched = False
+ break
+ if not matched:
+ continue
+ results.append(uuid)
+ return results
+
+
+
+class PostgreSQLGraphStore:
+ """
+ Graph driver that persists each brain into its own Postgres database.
+
+ The per-brain database is provisioned lazily through ``ensure_brain_database``
+ and accessed through the shared LRU pool registry. Each database owns a flat
+ schema (no ``brain_id`` columns, no ``kg_brains`` reference table) because
+ the brain identity is encoded in the database name itself.
+ """
+
+ _DDL = """
+ CREATE TABLE IF NOT EXISTS kg_nodes (
+ uuid TEXT PRIMARY KEY,
+ data JSONB NOT NULL
+ );
+ CREATE TABLE IF NOT EXISTS kg_relationships (
+ uuid TEXT PRIMARY KEY,
+ rel_type TEXT NOT NULL,
+ source_uuid TEXT NOT NULL,
+ target_uuid TEXT NOT NULL,
+ data JSONB NOT NULL
+ );
+ CREATE INDEX IF NOT EXISTS idx_kg_relationships_endpoints
+ ON kg_relationships(source_uuid, target_uuid);
+ """
+
+ def __init__(self) -> None:
+ config.postgresql.validate_credentials()
+ self._brains: dict[str, _BrainGraph] = {}
+ self._schema_ready: set[str] = set()
+ self._schema_lock = threading.Lock()
+
+ def _ensure_brain_schema(self, brain_id: str) -> None:
+ if brain_id in self._schema_ready:
+ return
+ with self._schema_lock:
+ if brain_id in self._schema_ready:
+ return
+ ensure_brain_database(brain_id)
+ with borrow(get_brain_pool(brain_id)) as conn:
+ with conn.cursor() as cur:
+ cur.execute(self._DDL)
+ conn.commit()
+ self._schema_ready.add(brain_id)
+
+ @contextmanager
+ def _connection(self, brain_id: str):
+ self._ensure_brain_schema(brain_id)
+ with borrow(get_brain_pool(brain_id)) as conn:
+ yield conn
+
+ def _ensure_brain_row(self, brain_id: str) -> None:
+ self._ensure_brain_schema(brain_id)
+
+ def get_brain(self, brain_id: str) -> _BrainGraph:
+ return self._load_brain(brain_id)
+
+ def _load_brain(self, brain_id: str) -> _BrainGraph:
+ if brain_id in self._brains:
+ return self._brains[brain_id]
+ self._ensure_brain_schema(brain_id)
+ brain = _BrainGraph(brain_id)
+ with self._connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute("SELECT uuid, data FROM kg_nodes")
+ for row in cur.fetchall():
+ data = dict(row["data"])
+ data["uuid"] = row["uuid"]
+ brain.graph.add_node(row["uuid"], **data)
+ cur.execute(
+ """
+ SELECT uuid, rel_type, source_uuid, target_uuid, data
+ FROM kg_relationships
+ """
+ )
+ for row in cur.fetchall():
+ payload = dict(row["data"])
+ payload["uuid"] = row["uuid"]
+ payload["rel_type"] = row["rel_type"]
+ brain.graph.add_edge(
+ row["source_uuid"],
+ row["target_uuid"],
+ key=row["uuid"],
+ **payload,
+ )
+ self._brains[brain_id] = brain
+ return brain
+
+ def _persist_node(self, brain_id: str, uuid: str, data: dict) -> None:
+ payload = dict(data)
+ payload.pop("uuid", None)
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ INSERT INTO kg_nodes (uuid, data)
+ VALUES (%s, %s::jsonb)
+ ON CONFLICT (uuid) DO UPDATE SET data = EXCLUDED.data
+ """,
+ (uuid, json.dumps(payload, default=str)),
+ )
+ conn.commit()
+
+ def _persist_relationship(
+ self,
+ brain_id: str,
+ uuid: str,
+ rel_type: str,
+ source_uuid: str,
+ target_uuid: str,
+ data: dict,
+ ) -> None:
+ payload = dict(data)
+ payload.pop("uuid", None)
+ payload.pop("rel_type", None)
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ INSERT INTO kg_relationships
+ (uuid, rel_type, source_uuid, target_uuid, data)
+ VALUES (%s, %s, %s, %s, %s::jsonb)
+ ON CONFLICT (uuid) DO UPDATE SET
+ rel_type = EXCLUDED.rel_type,
+ source_uuid = EXCLUDED.source_uuid,
+ target_uuid = EXCLUDED.target_uuid,
+ data = EXCLUDED.data
+ """,
+ (
+ uuid,
+ rel_type,
+ source_uuid,
+ target_uuid,
+ json.dumps(payload, default=str),
+ ),
+ )
+ conn.commit()
+
+ def _delete_node(self, brain_id: str, uuid: str) -> None:
+ brain = self._load_brain(brain_id)
+ if uuid in brain.graph:
+ brain.graph.remove_node(uuid)
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ "DELETE FROM kg_relationships WHERE source_uuid = %s OR target_uuid = %s",
+ (uuid, uuid),
+ )
+ cur.execute(
+ "DELETE FROM kg_nodes WHERE uuid = %s",
+ (uuid,),
+ )
+ conn.commit()
+
+ def _delete_relationship(self, brain_id: str, rel_uuid: str) -> None:
+ brain = self._load_brain(brain_id)
+ for source, target, key in list(brain.graph.edges(keys=True)):
+ if key == rel_uuid:
+ brain.graph.remove_edge(source, target, key)
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ "DELETE FROM kg_relationships WHERE uuid = %s",
+ (rel_uuid,),
+ )
+ conn.commit()
+
+ def ensure_database(self, database: str) -> None:
+ self._ensure_brain_row(database)
+ self._load_brain(database)
+
+ def merge_node(
+ self,
+ brain_id: str,
+ labels: list[str],
+ identification: dict[str, Any],
+ properties: dict[str, Any],
+ ) -> str:
+ brain = self._load_brain(brain_id)
+ merged_props = {**identification, **properties}
+ node_uuid = brain.upsert_node(labels, identification, merged_props)
+ self._persist_node(brain_id, node_uuid, brain.node_data(node_uuid))
+ return node_uuid
+
+ def merge_relationship(
+ self,
+ brain_id: str,
+ subject_labels: list[str],
+ subject_name: Any,
+ object_labels: list[str],
+ object_name: Any,
+ rel_type: str,
+ rel_props: dict[str, Any],
+ ) -> Optional[tuple[dict, dict]]:
+ brain = self._load_brain(brain_id)
+ source_uuid = self.resolve_node_by_name_labels(brain, subject_labels, subject_name)
+ target_uuid = self.resolve_node_by_name_labels(brain, object_labels, object_name)
+ if not source_uuid or not target_uuid:
+ return None
+ props = dict(rel_props)
+ props["rel_type"] = rel_type
+ rel_uuid = props.get("uuid") or f"{source_uuid}-{rel_type}-{target_uuid}"
+ props["uuid"] = rel_uuid
+ brain.graph.add_edge(source_uuid, target_uuid, key=rel_uuid, **props)
+ self._persist_relationship(
+ brain_id, rel_uuid, rel_type, source_uuid, target_uuid, props
+ )
+ return brain.node_data(source_uuid), brain.node_data(target_uuid)
+
+ def resolve_node_by_name_labels(
+ self, brain: _BrainGraph, labels: list[str], name: Any
+ ) -> Optional[str]:
+ for uuid, data in brain.graph.nodes(data=True):
+ if data.get("name") != name:
+ continue
+ if labels and not set(labels).issubset(set(data.get("labels") or [])):
+ continue
+ return uuid
+ return None
+
+ def match_nodes_by_uuid(self, brain: _BrainGraph, uuids: list[str]) -> list[dict]:
+ return [
+ self.node_to_record(brain, node_uuid)
+ for node_uuid in uuids
+ if node_uuid in brain.graph
+ ]
+
+ def neighborhood_records(self, brain: _BrainGraph, node_uuid: str) -> list[dict]:
+ records = []
+ if node_uuid not in brain.graph:
+ return records
+ for source, target, key in brain.graph.edges(keys=True):
+ if source != node_uuid and target != node_uuid:
+ continue
+ neighbor_uuid = target if source == node_uuid else source
+ record = self.relationship_to_record(brain, source, target, key, node_uuid)
+ record.update(
+ {
+ "m_uuid": neighbor_uuid,
+ "m_name": brain.node_data(neighbor_uuid).get("name"),
+ "m_labels": brain.labels(neighbor_uuid),
+ "m_description": brain.node_data(neighbor_uuid).get("description"),
+ "m_properties": brain.node_data(neighbor_uuid),
+ "m_polarity": brain.node_data(neighbor_uuid).get("polarity"),
+ "m_metadata": brain.node_data(neighbor_uuid).get("metadata"),
+ "m_happened_at": brain.node_data(neighbor_uuid).get("happened_at"),
+ "m_last_updated": brain.node_data(neighbor_uuid).get("last_updated"),
+ "m_observations": brain.node_data(neighbor_uuid).get("observations"),
+ }
+ )
+ records.append(record)
+ return records
+
+ def update_entity_properties(
+ self,
+ brain_id: str,
+ entity_uuid: str,
+ is_relationship: bool,
+ new_properties: dict[str, Any],
+ properties_to_remove: list[str],
+ ) -> Optional[dict]:
+ brain = self._load_brain(brain_id)
+ if is_relationship:
+ for source, target, key, data in brain.graph.edges(keys=True, data=True):
+ if data.get("uuid") != entity_uuid:
+ continue
+ for prop, value in new_properties.items():
+ data[prop] = value
+ for prop in properties_to_remove:
+ data.pop(prop, None)
+ self._persist_relationship(
+ brain_id, key, data.get("rel_type"), source, target, data
+ )
+ return {
+ "rel_type": data.get("rel_type"),
+ "rel_description": data.get("description"),
+ "properties": dict(data),
+ }
+ return None
+ if entity_uuid not in brain.graph:
+ return None
+ data = brain.node_data(entity_uuid)
+ for prop, value in new_properties.items():
+ data[prop] = value
+ for prop in properties_to_remove:
+ data.pop(prop, None)
+ self._persist_node(brain_id, entity_uuid, data)
+ return self.node_to_record(brain, entity_uuid)
+
+ def delete_nodes_by_uuids(self, brain_id: str, uuids: list[str]) -> list[dict]:
+ brain = self._load_brain(brain_id)
+ records = []
+ for node_uuid in uuids:
+ if node_uuid not in brain.graph:
+ continue
+ records.append(
+ {
+ "node": {
+ "uuid": node_uuid,
+ "name": brain.node_data(node_uuid).get("name"),
+ "labels": brain.labels(node_uuid),
+ "description": brain.node_data(node_uuid).get("description"),
+ "properties": brain.node_data(node_uuid),
+ "polarity": brain.node_data(node_uuid).get("polarity"),
+ "metadata": brain.node_data(node_uuid).get("metadata"),
+ "happened_at": brain.node_data(node_uuid).get("happened_at"),
+ "last_updated": brain.node_data(node_uuid).get("last_updated"),
+ "observations": brain.node_data(node_uuid).get("observations"),
+ }
+ }
+ )
+ self._delete_node(brain_id, node_uuid)
+ return records
+
+ def delete_relationships_by_uuids(self, brain_id: str, rel_uuids: list[str]) -> list[dict]:
+ brain = self._load_brain(brain_id)
+ records = []
+ for rel_uuid in rel_uuids:
+ for source, target, key, data in list(brain.graph.edges(keys=True, data=True)):
+ if key != rel_uuid and data.get("uuid") != rel_uuid:
+ continue
+ record = self.node_to_record(brain, source, "n")
+ record.update(self.relationship_to_record(brain, source, target, key, source))
+ record.update(self.node_to_record(brain, target, "m"))
+ records.append(record)
+ self._delete_relationship(brain_id, key)
+ return records
+
+ def list_labels(self, brain: _BrainGraph) -> list[str]:
+ return sorted(
+ {label for _, data in brain.graph.nodes(data=True) for label in data.get("labels", [])}
+ )
+
+ def list_relationship_types(self, brain: _BrainGraph) -> list[str]:
+ return sorted(
+ {
+ edge_data.get("rel_type")
+ for _, _, edge_data in brain.graph.edges(data=True)
+ if edge_data.get("rel_type")
+ }
+ )
+
+ def list_node_property_keys(self, brain: _BrainGraph) -> list[str]:
+ return sorted(
+ {
+ key
+ for _, data in brain.graph.nodes(data=True)
+ for key in data.keys()
+ if key not in {"labels", "uuid"}
+ }
+ )
+
+ def event_names(self, brain: _BrainGraph) -> list[str]:
+ return [
+ str(data.get("name"))
+ for _, data in brain.graph.nodes(data=True)
+ if "EVENT" in (data.get("labels") or []) and data.get("name")
+ ]
+
+ def check_node_exists(
+ self, brain: _BrainGraph, uuid: str, name: str, labels: list[str]
+ ) -> bool:
+ for node_uuid, data in brain.graph.nodes(data=True):
+ if node_uuid != uuid:
+ continue
+ if data.get("name") != name:
+ continue
+ if not set(labels).issubset(set(data.get("labels") or [])):
+ continue
+ return True
+ return False
+
+ def node_to_record(self, brain: _BrainGraph, uuid: str, alias: str = "n") -> dict:
+ data = brain.node_data(uuid)
+ record = {
+ f"{alias}_uuid" if alias != "n" else "uuid": uuid,
+ f"{alias}_name" if alias != "n" else "name": data.get("name"),
+ f"{alias}_labels" if alias != "n" else "labels": data.get("labels", []),
+ f"{alias}_description" if alias != "n" else "description": data.get("description"),
+ f"{alias}_properties" if alias != "n" else "properties": {
+ k: v for k, v in data.items() if k not in {"labels"}
+ },
+ "properties": {k: v for k, v in data.items() if k not in {"labels"}},
+ "polarity": data.get("polarity"),
+ "metadata": data.get("metadata"),
+ "happened_at": data.get("happened_at"),
+ "last_updated": data.get("last_updated"),
+ "observations": data.get("observations"),
+ }
+ if alias != "n":
+ record[f"{alias}_polarity"] = data.get("polarity")
+ record[f"{alias}_metadata"] = data.get("metadata")
+ record[f"{alias}_happened_at"] = data.get("happened_at")
+ record[f"{alias}_last_updated"] = data.get("last_updated")
+ record[f"{alias}_observations"] = data.get("observations")
+ return record
+
+ def relationship_to_record(
+ self,
+ brain: _BrainGraph,
+ source_uuid: str,
+ target_uuid: str,
+ rel_uuid: str,
+ direction_from: str,
+ ) -> dict:
+ edge_data = brain.graph.edges[source_uuid, target_uuid, rel_uuid]
+ rel_type = edge_data.get("rel_type") or edge_data.get("name") or ""
+ direction = "out" if direction_from == source_uuid else "in"
+ start = _NodeProxy(brain.node_data(source_uuid))
+ end = _NodeProxy(brain.node_data(target_uuid))
+ rel = _RelationshipProxy(
+ {
+ **edge_data,
+ "rel_type": rel_type,
+ "uuid": rel_uuid,
+ "description": edge_data.get("description"),
+ },
+ start,
+ end,
+ )
+ return {
+ "rel": rel,
+ "rel_type": rel_type,
+ "rel_description": edge_data.get("description"),
+ "rel_properties": dict(edge_data),
+ "rel_flowkey": edge_data.get("flow_key"),
+ "rel_uuid": rel_uuid,
+ "rel_last_updated": edge_data.get("last_updated"),
+ "rel_observations": edge_data.get("observations"),
+ "rel_amount": edge_data.get("amount"),
+ "direction": direction,
+ "r_direction": direction,
+ }
+
+ def neighbor_records_for_uuids(
+ self,
+ brain: _BrainGraph,
+ uuids: list[str],
+ same_type_only: bool = False,
+ of_types: Optional[list[str]] = None,
+ limit: Optional[int] = None,
+ ) -> list[dict]:
+ records = []
+ for node_uuid in uuids:
+ if node_uuid not in brain.graph:
+ continue
+ for source, target, key in brain.graph.edges(keys=True):
+ if source != node_uuid and target != node_uuid:
+ continue
+ neighbor_uuid = target if source == node_uuid else source
+ if same_type_only and not set(brain.labels(node_uuid)).intersection(brain.labels(neighbor_uuid)):
+ continue
+ if of_types and not set(of_types).intersection(brain.labels(neighbor_uuid)):
+ continue
+ record = self.node_to_record(brain, node_uuid)
+ record.update(self.relationship_to_record(brain, source, target, key, node_uuid))
+ record.update(
+ {
+ "c_uuid": neighbor_uuid,
+ "c_name": brain.node_data(neighbor_uuid).get("name"),
+ "c_labels": brain.labels(neighbor_uuid),
+ "c_description": brain.node_data(neighbor_uuid).get("description"),
+ "c_properties": brain.node_data(neighbor_uuid),
+ }
+ )
+ records.append(record)
+ if limit is not None and len(records) >= limit:
+ return records
+ return records
diff --git a/src/lib/postgresql/networkx.py b/src/lib/postgresql/networkx.py
new file mode 100644
index 0000000..9dd1b5e
--- /dev/null
+++ b/src/lib/postgresql/networkx.py
@@ -0,0 +1,16 @@
+"""
+File: /networkx.py
+Project: postgresql
+Created Date: Sunday May 24th 2026
+Author: Christian Nonis <[email protected]>
+"""
+
+from src.lib.postgresql.graph_store import GraphDatabaseError, PostgreSQLGraphStore
+from src.lib.postgresql.networkx_client import NetworkXGraphClient, get_networkx_graph_client
+
+__all__ = [
+ "GraphDatabaseError",
+ "PostgreSQLGraphStore",
+ "NetworkXGraphClient",
+ "get_networkx_graph_client",
+]
diff --git a/src/lib/postgresql/networkx_client.py b/src/lib/postgresql/networkx_client.py
new file mode 100644
index 0000000..81bce4d
--- /dev/null
+++ b/src/lib/postgresql/networkx_client.py
@@ -0,0 +1,1154 @@
+"""
+File: /networkx_client.py
+Project: postgresql
+Created Date: Sunday May 24th 2026
+Author: Christian Nonis <[email protected]>
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import os
+from typing import Any, Dict, List, Literal, Optional, Tuple
+
+from src.adapters.interfaces.embeddings import VectorStoreClient
+from src.adapters.interfaces.graph import GraphClient, PredicateWithFlowKey
+from src.constants.kg import (
+ IdentificationParams,
+ Node,
+ NodeDict,
+ Predicate,
+ PredicateDict,
+ SearchEntitiesResult,
+ SearchRelationshipsResult,
+ Triple,
+)
+from src.lib.postgresql.graph_store import (
+ GraphDatabaseError,
+ PostgreSQLGraphStore,
+ _RelationshipProxy,
+)
+from src.utils.serialization.data import always_dict
+
+
+class NetworkXGraphClient(GraphClient):
+ """
+ Graph client backed by PostgreSQL persistence and NetworkX in-memory traversal.
+ """
+
+ def __init__(self):
+ self._store = PostgreSQLGraphStore()
+
+ def ensure_database(self, database: str) -> None:
+ self._store.ensure_database(database)
+
+ def execute_operation(self, operation: str, brain_id: str) -> Any:
+ raise GraphDatabaseError(
+ "Ad-hoc Cypher operations are only supported with the Neo4j backend (GRAPH_DB=neo4j). "
+ "Use the native PostgreSQL+NetworkX graph API instead."
+ )
+
+ @property
+ def graphdb_type(self) -> str:
+ return "postgresql-networkx"
+
+ @property
+ def graphdb_description(self) -> str:
+ return (
+ "The graph database is PostgreSQL with NetworkX-backed in-memory traversal. "
+ "Use the native graph API methods; Cypher is not supported on this backend."
+ )
+
+ def _clean_labels(self, labels: list[str]) -> list[str]:
+ return [
+ label.replace(" ", "_")
+ .upper()
+ .replace("-", "_")
+ .replace(".", "_")
+ .replace(",", "_")
+ .replace(":", "_")
+ .replace(";", "_")
+ .replace("(", "_")
+ .replace(")", "_")
+ .replace("[", "_")
+ .replace("]", "_")
+ .replace("{", "_")
+ .replace("}", "_")
+ .replace("'", "_")
+ for label in labels
+ ]
+
+ def _clean_property_key(self, property_key: str) -> str:
+ words = property_key.split()
+ return words[0].lower() + "".join(word.capitalize() for word in words[1:])
+
+ def _format_property_key(self, property_key: str) -> str:
+ sanitized_key = property_key.rstrip("`").lstrip("`")
+ needs_quoting = any(
+ char in sanitized_key
+ for char in ["-", " ", ".", "+", "*", "/", "%", ":", "@", "#", "$"]
+ )
+ cleaned_key = self._clean_property_key(sanitized_key)
+ return f"`{cleaned_key}`" if needs_quoting else cleaned_key
+
+ def _format_value(self, value: Any) -> str:
+ if isinstance(value, str):
+ v = value.replace("'", "\\'")
+ return f"'{v}'"
+ if isinstance(value, (int, float, bool)):
+ return str(value)
+ if value is None:
+ return "null"
+ v = str(value).replace("'", "\\'")
+ return f"'{v}'"
+
+ def add_nodes(
+ self,
+ nodes: list[Node],
+ brain_id: str,
+ identification_params: Optional[dict] = None,
+ metadata: Optional[dict] = None,
+ ) -> list[Node] | str:
+ self._store.ensure_database(brain_id)
+ for node in nodes:
+ identification_dict: dict[str, Any] = {"name": node.name}
+ merged_metadata = {**(metadata or {}), **(node.metadata or {})}
+ all_properties: dict[str, Any] = {
+ **(node.properties or {}),
+ "metadata": merged_metadata or None,
+ }
+ if identification_params:
+ for key, value in identification_params.items():
+ normalized_key = self._clean_property_key(key)
+ if normalized_key != "name":
+ identification_dict[normalized_key] = value
+ for attr in (
+ "description",
+ "happened_at",
+ "last_updated",
+ "observations",
+ "polarity",
+ ):
+ if getattr(node, attr, None) is not None:
+ all_properties[attr] = getattr(node, attr)
+ all_properties["uuid"] = node.uuid
+ self._store.merge_node(
+ brain_id,
+ self._clean_labels(node.labels),
+ identification_dict,
+ all_properties,
+ )
+ return [
+ Node(
+ uuid=node.uuid,
+ labels=node.labels,
+ name=node.name,
+ description=node.description,
+ properties=node.properties,
+ metadata={**(node.metadata or {}), **(metadata or {})},
+ )
+ for node in nodes
+ ]
+
+ def add_relationship(
+ self,
+ subject: Node,
+ predicate: Predicate,
+ to_object: Node,
+ brain_id: str,
+ ) -> str:
+ rel_props: dict[str, Any] = {
+ "description": predicate.description,
+ "uuid": predicate.uuid,
+ "v_id": (predicate.properties or {}).get("v_id"),
+ "flow_key": predicate.flow_key,
+ }
+ for attr in ("properties", "happened_at", "last_updated", "amount"):
+ value = getattr(predicate, attr, None)
+ if value:
+ rel_props[attr] = value
+ for attr in ("properties", "description", "happened_at", "flow_key", "last_updated", "amount"):
+ for obj in (subject, to_object):
+ value = getattr(obj, attr, None)
+ if value and attr not in rel_props:
+ rel_props[attr] = value
+ self._store.ensure_database(brain_id)
+ self._store.merge_relationship(
+ brain_id,
+ self._clean_labels(subject.labels),
+ subject.name,
+ self._clean_labels(to_object.labels),
+ to_object.name,
+ self._clean_labels([predicate.name])[0],
+ rel_props,
+ )
+ return "ok"
+
+ def search_graph(self, nodes: list[Node], brain_id: str) -> list[Node]:
+ if not nodes:
+ return []
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ records = []
+ for node in nodes:
+ node_uuid = self._store.resolve_node_by_name_labels(
+ brain, self._clean_labels(node.labels), node.name
+ )
+ if not node_uuid:
+ continue
+ records.append({"n": brain.node_data(node_uuid), "r": None, "m": None})
+ for source, target, key in brain.graph.edges(keys=True):
+ if source != node_uuid and target != node_uuid:
+ continue
+ neighbor_uuid = target if source == node_uuid else source
+ records.append(
+ {
+ "n": brain.node_data(node_uuid),
+ "r": brain.graph.edges[source, target, key],
+ "m": brain.node_data(neighbor_uuid),
+ }
+ )
+ return records
+
+
+ def node_text_search(self, text: str, brain_id: str) -> list[Node]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ text_lower = text.lower()
+ nodes = []
+ for node_uuid, data in brain.graph.nodes(data=True):
+ if text_lower in str(data.get("name", "")).lower():
+ nodes.append(
+ Node(
+ uuid=node_uuid,
+ name=data.get("name", "") or "",
+ labels=list(data.get("labels") or []),
+ description=data.get("description", "") or "",
+ properties={k: v for k, v in data.items() if k != "labels"},
+ )
+ )
+ return nodes
+
+
+ def get_nodes_by_uuid(
+ self,
+ uuids: list[str],
+ brain_id: str,
+ with_relationships: Optional[bool] = False,
+ relationships_depth: Optional[int] = 1,
+ relationships_type: Optional[list[str]] = None,
+ preferred_labels: Optional[list[str]] = None,
+ ) -> list[dict]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ depth = relationships_depth or 1
+ rel_types = relationships_type
+ pref = self._clean_labels(preferred_labels) if preferred_labels else None
+ if not with_relationships:
+ return [
+ Node(
+ uuid=record["uuid"],
+ name=record["name"],
+ labels=record["labels"],
+ description=record["description"],
+ properties=record["properties"],
+ )
+ for record in self._store.match_nodes_by_uuid(brain, uuids)
+ ]
+ records = []
+ for node_uuid in uuids:
+ if node_uuid not in brain.graph:
+ continue
+ visited = {node_uuid}
+ frontier = {node_uuid}
+ for _ in range(depth):
+ next_frontier: set[str] = set()
+ for current_uuid in frontier:
+ for source, target, key, edge_data in brain.graph.edges(keys=True, data=True):
+ neighbor = target if source == current_uuid else source
+ if neighbor in visited:
+ continue
+ if rel_types and edge_data.get("rel_type") not in rel_types:
+ continue
+ neighbor_labels = brain.labels(neighbor)
+ if pref and not set(pref).intersection(neighbor_labels):
+ continue
+ record = self._store.node_to_record(brain, node_uuid)
+ record.update(
+ self._store.relationship_to_record(
+ brain, source, target, key, current_uuid
+ )
+ )
+ record.update(
+ {
+ "m_uuid": neighbor,
+ "m_name": brain.node_data(neighbor).get("name"),
+ "m_labels": neighbor_labels,
+ "m_description": brain.node_data(neighbor).get("description"),
+ "m_properties": brain.node_data(neighbor),
+ }
+ )
+ records.append(record)
+ visited.add(neighbor)
+ next_frontier.add(neighbor)
+ frontier = next_frontier
+ return [
+ {
+ "node": Node(
+ uuid=record["uuid"],
+ name=record["name"],
+ labels=record["labels"],
+ description=record["description"],
+ properties=record["properties"],
+ ),
+ "relationships": record.get("rel"),
+ "related_nodes": (
+ Node(
+ uuid=record["m_uuid"],
+ name=record["m_name"],
+ labels=record["m_labels"],
+ description=record["m_description"],
+ properties=record["m_properties"],
+ )
+ if record.get("m_uuid")
+ else None
+ ),
+ }
+ for record in records
+ ]
+
+
+ def get_graph_entities(self, brain_id: str) -> list[str]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ labels: list[str] = []
+ for node_uuid in brain.graph.nodes:
+ labels.extend(brain.labels(node_uuid))
+ return labels
+
+
+ def get_graph_relationships(self, brain_id: str) -> list[str]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return self._store.list_relationship_types(brain)
+
+
+ def get_by_uuid(self, uuid: str, brain_id: str) -> Node:
+ nodes = self.get_by_uuids([uuid], brain_id)
+ return nodes[0] if nodes else None
+
+
+ def get_by_uuids(self, uuids: list[str], brain_id: str) -> list[Node]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return [
+ Node(
+ uuid=record.get("uuid", ""),
+ name=record.get("name", ""),
+ labels=record.get("labels", []),
+ description=record.get("description", ""),
+ properties=record.get("properties", {}),
+ polarity=record.get("polarity", "neutral"),
+ **(
+ {"happened_at": record.get("happened_at")}
+ if record.get("happened_at") is not None
+ else {}
+ ),
+ **(
+ {"last_updated": record.get("last_updated", datetime.now(timezone.utc))}
+ if record.get("last_updated") is not None
+ else {}
+ ),
+ **(
+ {"observations": record.get("observations", [])}
+ if record.get("observations") is not None
+ else {}
+ ),
+ **(
+ {"metadata": record.get("metadata", {})}
+ if record.get("metadata") is not None
+ else {}
+ ),
+ )
+ for record in self._store.match_nodes_by_uuid(brain, uuids)
+ ]
+
+
+ def get_by_identification_params(
+ self,
+ identification_params: IdentificationParams,
+ brain_id: str,
+ entity_types: Optional[list[str]] = None,
+ ) -> Node:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ params_dict = identification_params.model_dump(mode="json", exclude={"entity_types"})
+ labels = self._clean_labels(entity_types) if entity_types else None
+ matches = brain.find_nodes(labels=labels or None, filters=params_dict)
+ if not matches:
+ return None
+ record = self._store.node_to_record(brain, matches[0])
+ return Node(
+ uuid=record.get("uuid", ""),
+ name=record.get("name", "") or "",
+ labels=record.get("labels", []) or [],
+ description=record.get("description", "") or "",
+ properties=record.get("properties", {}) or {},
+ )
+
+
+ def get_neighbors(
+ self,
+ nodes: list[Node | str],
+ brain_id: str,
+ same_type_only: bool = False,
+ limit: int | None = None,
+ of_types: Optional[list[str]] = None,
+ ) -> Dict[str, List[Tuple[Predicate, Node]]]:
+ if len(nodes) == 0:
+ return {}
+ node_uuids = nodes if isinstance(nodes[0], str) else [node.uuid for node in nodes]
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ cleaned_types = self._clean_labels(of_types) if of_types else None
+ records = self._store.neighbor_records_for_uuids(
+ brain, node_uuids, same_type_only, cleaned_types, limit
+ )
+ neighbors_dict: Dict[str, List[Tuple[Predicate, Node]]] = {uuid: [] for uuid in node_uuids}
+ for record in records:
+ source_uuid = record["uuid"]
+ neighbor = (
+ Predicate(
+ name=record.get("rel_type", "") or "",
+ description=record.get("rel_description", "") or "",
+ direction=record.get("direction", "neutral"),
+ properties=record.get("rel_properties", {}) or {},
+ flow_key=record.get("rel_flowkey", "") or "",
+ uuid=record.get("rel_uuid", "") or "",
+ ),
+ Node(
+ uuid=record.get("c_uuid", ""),
+ name=record.get("c_name", "") or "",
+ labels=record.get("c_labels", []) or [],
+ description=record.get("c_description", "") or "",
+ properties=record.get("c_properties", {}) or {},
+ ),
+ )
+ if source_uuid in neighbors_dict:
+ neighbors_dict[source_uuid].append(neighbor)
+ return neighbors_dict
+
+
+ def get_node_with_rel_by_uuid(
+ self, rel_ids_with_node_ids: list[tuple[str, str]], brain_id: str
+ ) -> list[dict]:
+ """
+ Get the node with the relationships by their UUIDs.
+ """
+
+ def get_neighbor_node_tuples(
+ self, a_uuid: str, b_uuids: list[str], brain_id: str
+ ) -> list[Tuple[Node, Predicate, Node]]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ b_set = set(b_uuids)
+ tuples = []
+ for source, target, key, edge_data in brain.graph.edges(keys=True, data=True):
+ if source != a_uuid and target != a_uuid:
+ continue
+ neighbor = target if source == a_uuid else source
+ if neighbor not in b_set:
+ continue
+ n_uuid, m_uuid = a_uuid, neighbor
+ direction = "out" if source == a_uuid else "in"
+ tuples.append(
+ (
+ Node(
+ uuid=n_uuid,
+ name=brain.node_data(n_uuid).get("name", "") or "",
+ labels=brain.labels(n_uuid),
+ description=brain.node_data(n_uuid).get("description", "") or "",
+ properties=brain.node_data(n_uuid),
+ ),
+ Predicate(
+ name=edge_data.get("rel_type", "") or "",
+ description=edge_data.get("description", "") or "",
+ direction=direction,
+ ),
+ Node(
+ uuid=m_uuid,
+ name=brain.node_data(m_uuid).get("name", "") or "",
+ labels=brain.labels(m_uuid),
+ description=brain.node_data(m_uuid).get("description", "") or "",
+ properties=brain.node_data(m_uuid),
+ ),
+ )
+ )
+ if not tuples and os.getenv("DEBUG") == "true":
+ raise ValueError(
+ f"No neighbor nodes found for UUID: {a_uuid} and b_uuids: {b_uuids}"
+ )
+ return tuples
+
+
+ def get_connected_nodes(
+ self,
+ brain_id: str,
+ node: Optional[Node] = None,
+ uuids: Optional[list[str]] = None,
+ limit: Optional[int] = 10,
+ with_labels: Optional[list[str]] = None,
+ ) -> list[Tuple[Node, Predicate, Node]]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ start_uuids: set[str] = set()
+ if node:
+ start_uuids.add(node.uuid)
+ if uuids:
+ start_uuids.update(uuids)
+ label_filter = set(with_labels) if with_labels else None
+ results = []
+ for source, target, key, edge_data in brain.graph.edges(keys=True, data=True):
+ if start_uuids and source not in start_uuids and target not in start_uuids:
+ continue
+ anchor = source if source in start_uuids or not start_uuids else target
+ other = target if anchor == source else source
+ if label_filter and not label_filter.intersection(brain.labels(other)):
+ continue
+ direction = "out" if anchor == source else "in"
+ results.append(
+ (
+ Node(
+ uuid=other,
+ name=brain.node_data(other).get("name", "") or "",
+ labels=brain.labels(other),
+ description=brain.node_data(other).get("description", "") or "",
+ properties=brain.node_data(other),
+ ),
+ Predicate(
+ name=edge_data.get("rel_type", "") or "",
+ description=edge_data.get("description", "") or "",
+ direction=direction,
+ ),
+ Node(
+ uuid=anchor,
+ name=brain.node_data(anchor).get("name", "") or "",
+ labels=brain.labels(anchor),
+ description=brain.node_data(anchor).get("description", "") or "",
+ properties=brain.node_data(anchor),
+ ),
+ )
+ )
+ if limit is not None and len(results) >= limit:
+ break
+ return results
+
+
+ def search_relationships(
+ self,
+ brain_id: str,
+ limit: int = 10,
+ skip: int = 0,
+ relationship_types: Optional[list[str]] = None,
+ from_node_labels: Optional[list[str]] = None,
+ to_node_labels: Optional[list[str]] = None,
+ relationship_uuids: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ query_search_target: Optional[str] = "all",
+ ) -> SearchRelationshipsResult:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ text_lower = query_text.lower() if query_text else None
+ from_labels = set(self._clean_labels(from_node_labels)) if from_node_labels else None
+ to_labels = set(self._clean_labels(to_node_labels)) if to_node_labels else None
+ matched = []
+ for source, target, key, edge_data in brain.graph.edges(keys=True, data=True):
+ rel_type = edge_data.get("rel_type")
+ if relationship_types and rel_type not in relationship_types:
+ continue
+ if relationship_uuids and key not in relationship_uuids and edge_data.get("uuid") not in relationship_uuids:
+ continue
+ if from_labels and not from_labels.intersection(brain.labels(source)):
+ continue
+ if to_labels and not to_labels.intersection(brain.labels(target)):
+ continue
+ if text_lower:
+ haystacks = [
+ str(brain.node_data(source).get("name", "")).lower(),
+ str(brain.node_data(target).get("name", "")).lower(),
+ str(edge_data.get("description", "")).lower(),
+ ]
+ if query_search_target == "node_name":
+ haystacks = [str(brain.node_data(source).get("name", "")).lower()]
+ elif query_search_target == "relationship_description":
+ haystacks = [str(edge_data.get("description", "")).lower()]
+ elif query_search_target == "relationship_name":
+ haystacks = [str(rel_type or "").lower()]
+ if not any(text_lower in h for h in haystacks):
+ continue
+ matched.append((source, target, key, edge_data))
+ total = len(matched)
+ page = matched[skip : skip + limit]
+ triples: list[Triple] = []
+ for source, target, key, edge_data in page:
+ direction = "out"
+ triples.append(
+ Triple(
+ subject=Node(
+ uuid=source,
+ name=str(brain.node_data(source).get("name") or source),
+ labels=list(brain.labels(source)),
+ description=brain.node_data(source).get("description"),
+ properties=brain.node_data(source),
+ ),
+ predicate=Predicate(
+ name=str(edge_data.get("rel_type") or ""),
+ description=edge_data.get("description") or "",
+ direction=direction,
+ observations=None,
+ level=None,
+ deprecated=edge_data.get("deprecated", False),
+ ),
+ object=Node(
+ uuid=target,
+ name=str(brain.node_data(target).get("name") or target),
+ labels=list(brain.labels(target)),
+ description=brain.node_data(target).get("description"),
+ properties=brain.node_data(target),
+ ),
+ )
+ )
+ return SearchRelationshipsResult(results=triples, total=total)
+
+
+ def search_entities(
+ self,
+ brain_id: str,
+ limit: int = 10,
+ skip: int = 0,
+ node_labels: Optional[list[str]] = None,
+ node_uuids: Optional[list[str]] = None,
+ query_text: Optional[str] = None,
+ ) -> SearchEntitiesResult:
+ self.ensure_database(brain_id)
+ brain = self._store._load_brain(brain_id)
+ allowed_labels = (
+ set(self._clean_labels(node_labels)) if node_labels else None
+ )
+ uuid_filter = set(node_uuids) if node_uuids else None
+ text_lower = query_text.lower() if query_text else None
+
+ matched: list[str] = []
+ for node_uuid, data in brain.graph.nodes(data=True):
+ if uuid_filter is not None and node_uuid not in uuid_filter:
+ continue
+ if allowed_labels is not None:
+ if not allowed_labels.intersection(set(brain.labels(node_uuid))):
+ continue
+ if text_lower is not None:
+ if text_lower not in str(data.get("name", "")).lower():
+ continue
+ matched.append(node_uuid)
+
+ total = len(matched)
+ page = matched[skip : skip + limit]
+
+ nodes: list[Node] = []
+ for node_uuid in page:
+ data = brain.node_data(node_uuid)
+ properties = {k: v for k, v in data.items() if k != "labels"}
+ nodes.append(
+ Node(
+ uuid=str(node_uuid),
+ name=str(data.get("name") or node_uuid),
+ labels=list(brain.labels(node_uuid)),
+ description=data.get("description"),
+ properties=properties,
+ )
+ )
+ return SearchEntitiesResult(results=nodes, total=total)
+
+ def deprecate_relationship(
+ self,
+ subject: Node,
+ predicate: Predicate,
+ object: Node,
+ brain_id: str,
+ ) -> Tuple[Node, Predicate, Node] | None:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ source_uuid = self._store.resolve_node_by_name_labels(
+ brain, self._clean_labels(subject.labels), subject.name
+ )
+ target_uuid = self._store.resolve_node_by_name_labels(
+ brain, self._clean_labels(object.labels), object.name
+ )
+ if not source_uuid or not target_uuid:
+ return None
+ rel_type = self._clean_labels([predicate.name])[0]
+ for source, target, key, data in brain.graph.edges(keys=True, data=True):
+ if source != source_uuid or target != target_uuid:
+ continue
+ if data.get("rel_type") != rel_type:
+ continue
+ data["deprecated"] = True
+ self._store._persist_relationship(
+ brain_id, key, rel_type, source, target, data
+ )
+ return (
+ Node(
+ uuid=source_uuid,
+ name=subject.name,
+ labels=subject.labels,
+ description=subject.description,
+ properties=brain.node_data(source_uuid),
+ ),
+ Predicate(
+ name=rel_type,
+ description=data.get("description", "") or "",
+ direction="out",
+ ),
+ Node(
+ uuid=target_uuid,
+ name=object.name,
+ labels=object.labels,
+ description=object.description,
+ properties=brain.node_data(target_uuid),
+ ),
+ )
+ return None
+
+
+ def update_properties(
+ self,
+ uuid: str,
+ updating: Literal["node", "relationship"],
+ brain_id: str,
+ new_properties: dict,
+ properties_to_remove: list[str],
+ ) -> Node | Predicate | None:
+ self._store.ensure_database(brain_id)
+ record = self._store.update_entity_properties(
+ brain_id,
+ uuid,
+ updating == "relationship",
+ new_properties,
+ properties_to_remove,
+ )
+ if not record:
+ return None
+ if updating == "node":
+ return Node(
+ uuid=record.get("uuid", "") or "",
+ name=record.get("name", "") or "",
+ labels=record.get("labels", []) or [],
+ description=record.get("description", "") or "",
+ properties=record.get("properties", {}) or {},
+ )
+ return Predicate(
+ name=record.get("rel_type", "") or "",
+ description=record.get("rel_description", "") or "",
+ direction=record.get("direction", "neutral"),
+ )
+
+
+ def get_graph_relationship_types(self, brain_id: str) -> list[str]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return self._store.list_relationship_types(brain)
+
+
+ def get_graph_node_types(self, brain_id: str) -> list[str]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return self._store.list_labels(brain)
+
+
+ def get_graph_node_properties(self, brain_id: str) -> list[str]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return self._store.list_node_property_keys(brain)
+
+
+ def update_node(
+ self,
+ uuid: str,
+ brain_id: str,
+ new_name: Optional[str] = None,
+ new_description: Optional[str] = None,
+ new_labels: Optional[list[str]] = None,
+ new_properties: Optional[dict] = None,
+ properties_to_remove: Optional[list[str]] = None,
+ ) -> Node | None:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ if uuid not in brain.graph:
+ return None
+ existing_node = self.get_by_uuid(uuid, brain_id)
+ if (
+ not new_name
+ and not new_description
+ and not new_labels
+ and not new_properties
+ and not properties_to_remove
+ ):
+ return existing_node
+ data = brain.node_data(uuid)
+ if new_name:
+ data["name"] = new_name
+ if new_description:
+ data["description"] = new_description
+ if new_labels:
+ data["labels"] = self._clean_labels(new_labels)
+ if new_properties:
+ existing_properties = (existing_node.properties or {}) if existing_node else {}
+ for property_key, new_value in new_properties.items():
+ key_str = self._clean_property_key(property_key)
+ if property_key not in existing_properties or existing_properties.get(property_key) != new_value:
+ data[key_str] = new_value
+ if properties_to_remove:
+ for prop in properties_to_remove:
+ data.pop(self._clean_property_key(prop), None)
+ self._store._persist_node(brain_id, uuid, data)
+ record = self._store.node_to_record(brain, uuid)
+ return Node(
+ uuid=record.get("uuid", "") or "",
+ name=record.get("name", "") or "",
+ labels=record.get("labels", []) or [],
+ description=record.get("description", "") or "",
+ properties=record.get("properties", {}) or {},
+ )
+
+
+ def get_schema(self, brain_id: str) -> dict:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return {
+ "labels": self._store.list_labels(brain),
+ "relationships": self._store.list_relationship_types(brain),
+ "event_names": self._store.event_names(brain),
+ }
+
+
+ def get_2nd_degree_hops(
+ self,
+ from_: List[str],
+ flattened: bool,
+ vector_store_adapter: VectorStoreClient,
+ brain_id: str,
+ ) -> Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]:
+ """
+ Retrieve second-degree neighbor nodes from the given starting nodes.
+
+ Parameters:
+ from_ (List[str]): List of node UUIDs to start the hop from.
+ flattened (bool): Whether to flatten the result structure.
+ vector_store_adapter (VectorStoreClient): Adapter to the vector store.
+ brain_id (str): Identifier of the brain or graph context.
+
+ Returns:
+ Dict[str, List[Tuple[Predicate, Node, List[Tuple[Predicate, Node]]]]]: Mapping from each starting node UUID to a list of tuples containing
+ a predicate to a neighbor node, the neighbor node itself, and a list of tuples for that neighbor's predicates and their connected nodes.
+ """
+ return super().get_2nd_degree_hops(
+ from_, flattened, vector_store_adapter, brain_id
+ )
+
+ def check_node_existence(
+ self,
+ uuid: str,
+ name: str,
+ labels: list[str],
+ brain_id: str,
+ ) -> bool:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ return self._store.check_node_exists(
+ brain, uuid, name, self._clean_labels(labels)
+ )
+
+
+ def get_neighborhood(
+ self, node: Node | str, depth: int, brain_id: str
+ ) -> list[dict]:
+ if depth < 1:
+ return []
+ node_uuid = node.uuid if isinstance(node, Node) else node
+ return self._get_neighborhood_recursive(node_uuid, depth, brain_id, set())
+
+
+ def _get_neighborhood_recursive(
+ self, node_uuid: str, depth: int, brain_id: str, path_visited: set[str]
+ ) -> list[dict]:
+ if depth < 1 or node_uuid in path_visited:
+ return []
+ path_visited = path_visited.copy()
+ path_visited.add(node_uuid)
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ records = self._store.neighborhood_records(brain, node_uuid)
+ neighbors = []
+ for record in records:
+ neighbor_node_uuid = record.get("m_uuid", "")
+ if neighbor_node_uuid in path_visited:
+ continue
+ neighbor_node = Node(
+ uuid=neighbor_node_uuid,
+ name=record.get("m_name", "") or "",
+ labels=record.get("m_labels", []) or [],
+ description=record.get("m_description", "") or "",
+ properties=always_dict(record.get("m_properties", {})),
+ polarity=record.get("m_polarity", "neutral"),
+ metadata=always_dict(record.get("m_metadata", {})),
+ happened_at=record.get("m_happened_at", "") or "",
+ last_updated=record.get("m_last_updated", "") or "",
+ observations=record.get("m_observations", []) or [],
+ )
+ predicate = Predicate(
+ name=record.get("rel_type", "") or "",
+ description=record.get("rel_description", "") or "",
+ direction=record.get("direction", "neutral"),
+ properties=always_dict(record.get("rel_properties", {})),
+ flow_key=record.get("rel_flowkey", "") or "",
+ uuid=record.get("rel_uuid", "") or "",
+ last_updated=record.get("rel_last_updated", "") or "",
+ observations=record.get("rel_observations", []) or [],
+ amount=record.get("rel_amount"),
+ )
+ nested_neighbors = self._get_neighborhood_recursive(
+ neighbor_node_uuid, depth - 1, brain_id, path_visited
+ )
+ neighbors.append(
+ {
+ "predicate": predicate,
+ "node": neighbor_node,
+ "neighbors": nested_neighbors,
+ }
+ )
+ return neighbors
+
+
+ def get_event_centric_neighbors(
+ self,
+ nodes: list[Node | str],
+ brain_id: str,
+ ) -> List[Tuple[Node, Predicate, Node, Predicate, Node]]:
+ if len(nodes) == 0:
+ return []
+ node_uuids = nodes if isinstance(nodes[0], str) else [node.uuid for node in nodes]
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ results = []
+ for n_uuid, m_uuid, b_uuid, r1_data, r2_data, _, _ in self._event_path_records(brain, node_uuids):
+ r_direction = "out"
+ r2_direction = "out"
+ results.append(
+ (
+ self._node_from_brain(brain, n_uuid),
+ self._predicate_from_edge(r1_data, r_direction),
+ self._node_from_brain(brain, m_uuid),
+ self._predicate_from_edge(r2_data, r2_direction),
+ self._node_from_brain(brain, b_uuid),
+ )
+ )
+ return results
+
+
+ def get_nexts_by_flow_key(
+ self, predicates: list[PredicateWithFlowKey], brain_id: str
+ ) -> Dict[str, List[Tuple[Node, Predicate, Node]]]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ res: Dict[str, List[Tuple[Node, Predicate, Node]]] = {}
+ for predicate in predicates:
+ paths = self._event_path_records(
+ brain,
+ list(brain.graph.nodes),
+ predicate_uuid=predicate["predicate_uuid"],
+ flow_key=predicate["flow_key"],
+ )
+ res[predicate["predicate_uuid"]] = [
+ (
+ self._node_from_brain(brain, m_uuid),
+ self._predicate_from_edge(r2_data, "out"),
+ self._node_from_brain(brain, b_uuid),
+ )
+ for _, m_uuid, b_uuid, _, r2_data, _, _ in paths
+ ]
+ return res
+
+
+ def get_triples_by_uuid(
+ self, uuids: list[str], brain_id: str
+ ) -> List[Tuple[Node, Predicate, Node]]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ uuid_set = set(uuids)
+ triples = []
+ for source, target, key, edge_data in brain.graph.edges(keys=True, data=True):
+ if key not in uuid_set and edge_data.get("uuid") not in uuid_set:
+ continue
+ triples.append(
+ (
+ Node(
+ uuid=source,
+ name=brain.node_data(source).get("name", "") or "",
+ labels=brain.labels(source),
+ description=brain.node_data(source).get("description", "") or "",
+ properties=brain.node_data(source),
+ ),
+ Predicate(
+ name=edge_data.get("rel_type", "") or "",
+ description=edge_data.get("description", "") or "",
+ direction="neutral",
+ properties=dict(edge_data),
+ ),
+ Node(
+ uuid=target,
+ name=brain.node_data(target).get("name", "") or "",
+ labels=brain.labels(target),
+ description=brain.node_data(target).get("description", "") or "",
+ properties=brain.node_data(target),
+ ),
+ )
+ )
+ return triples
+
+
+ def remove_nodes(self, uuids: list[str], brain_id: str) -> list[Node]:
+ self._store.ensure_database(brain_id)
+ records = self._store.delete_nodes_by_uuids(brain_id, uuids)
+ return [Node(**record.get("node", {})) for record in records]
+
+
+ def remove_relationships(
+ self,
+ relationships: list[Tuple[NodeDict, PredicateDict, NodeDict]],
+ brain_id: str,
+ ) -> list[Tuple[Node, Predicate, Node]]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ deleted: list[Tuple[Node, Predicate, Node]] = []
+ by_rel_uuid: list[str] = []
+ by_tip_tail: list[Tuple[NodeDict, PredicateDict, NodeDict]] = []
+ for tail, pred, head in relationships:
+ if pred.get("uuid"):
+ by_rel_uuid.append(pred["uuid"])
+ else:
+ by_tip_tail.append((tail, pred, head))
+ if by_rel_uuid:
+ records = self._store.delete_relationships_by_uuids(brain_id, by_rel_uuid)
+ for record in records:
+ deleted.append(self._record_to_triple(record))
+ for tail, pred, head in by_tip_tail:
+ tail_uuid = self._resolve_node_dict(brain, tail)
+ head_uuid = self._resolve_node_dict(brain, head)
+ rel_type = pred.get("name")
+ if not tail_uuid or not head_uuid:
+ continue
+ for source, target, key, edge_data in list(brain.graph.edges(keys=True, data=True)):
+ if {source, target} != {tail_uuid, head_uuid}:
+ continue
+ if rel_type and edge_data.get("rel_type") != self._clean_labels([rel_type])[0]:
+ continue
+ record = self._store.node_to_record(brain, source, "n")
+ record.update(self._store.relationship_to_record(brain, source, target, key, source))
+ record.update(self._store.node_to_record(brain, target, "m"))
+ deleted.append(self._record_to_triple(record))
+ self._store._delete_relationship(brain_id, key)
+ return deleted
+
+
+ def _record_to_triple(self, record: Any) -> Tuple[Node, Predicate, Node]:
+ return (
+ Node(
+ uuid=record.get("n_uuid", "") or "",
+ name=record.get("n_name", "") or "",
+ labels=record.get("n_labels", []) or [],
+ description=record.get("n_description", "") or "",
+ properties=record.get("n_properties", {}) or {},
+ ),
+ Predicate(
+ uuid=record.get("r_uuid", "") or "",
+ name=record.get("r_type", "") or "",
+ description=record.get("r_description", "") or "",
+ direction="neutral",
+ properties=record.get("r_properties", {}) or {},
+ ),
+ Node(
+ uuid=record.get("m_uuid", "") or "",
+ name=record.get("m_name", "") or "",
+ labels=record.get("m_labels", []) or [],
+ description=record.get("m_description", "") or "",
+ properties=record.get("m_properties", {}) or {},
+ ),
+ )
+
+ def list_relationships(
+ self, subject: str, object: str, brain_id: str
+ ) -> list[Tuple[Node, Predicate, Node]]:
+ self._store.ensure_database(brain_id)
+ brain = self._store.get_brain(brain_id)
+ triples = []
+ for source, target, key, edge_data in brain.graph.edges(keys=True, data=True):
+ if {source, target} != {subject, object}:
+ continue
+ triples.append(
+ (
+ Node(
+ uuid=source,
+ name=brain.node_data(source).get("name", "") or "",
+ labels=brain.labels(source),
+ description=brain.node_data(source).get("description", "") or "",
+ properties=brain.node_data(source),
+ polarity=brain.node_data(source).get("polarity", "neutral"),
+ metadata=brain.node_data(source).get("metadata", {}) or {},
+ happened_at=brain.node_data(source).get("happened_at", "") or "",
+ last_updated=brain.node_data(source).get("last_updated", "") or "",
+ observations=brain.node_data(source).get("observations", []) or [],
+ ),
+ Predicate(
+ uuid=edge_data.get("uuid", key) or "",
+ name=edge_data.get("rel_type", "") or "",
+ description=edge_data.get("description", "") or "",
+ direction="neutral",
+ properties=dict(edge_data),
+ flow_key=edge_data.get("flow_key", "") or "",
+ last_updated=edge_data.get("last_updated", "") or "",
+ observations=edge_data.get("observations", []) or [],
+ amount=edge_data.get("amount"),
+ ),
+ Node(
+ uuid=target,
+ name=brain.node_data(target).get("name", "") or "",
+ labels=brain.labels(target),
+ description=brain.node_data(target).get("description", "") or "",
+ properties=brain.node_data(target),
+ polarity=brain.node_data(target).get("polarity", "neutral"),
+ metadata=brain.node_data(target).get("metadata", {}) or {},
+ happened_at=brain.node_data(target).get("happened_at", "") or "",
+ last_updated=brain.node_data(target).get("last_updated", "") or "",
+ observations=brain.node_data(target).get("observations", []) or [],
+ ),
+ )
+ )
+ return triples
+
+
+def _records(data: list | Any) -> Any:
+ if hasattr(data, "records"):
+ return data
+ class _R:
+ def __init__(self, records):
+ self.records = records
+ return _R(data if isinstance(data, list) else [])
+
+
+_networkx_graph_client: Optional[NetworkXGraphClient] = None
+
+
+def get_networkx_graph_client() -> NetworkXGraphClient:
+ global _networkx_graph_client
+ if _networkx_graph_client is None:
+ _networkx_graph_client = NetworkXGraphClient()
+ return _networkx_graph_client
diff --git a/src/lib/postgresql/vectors.py b/src/lib/postgresql/vectors.py
new file mode 100644
index 0000000..104b767
--- /dev/null
+++ b/src/lib/postgresql/vectors.py
@@ -0,0 +1,366 @@
+"""
+File: /vectors.py
+Project: postgresql
+Created Date: Sunday May 24th 2026
+Author: Christian Nonis <[email protected]>
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import hashlib
+import json
+import logging
+import re
+import threading
+from typing import Any, Iterator, Optional
+
+import psycopg2
+import psycopg2.extras
+from pgvector.psycopg2 import register_vector
+
+from src.adapters.interfaces.embeddings import VectorStoreClient
+from src.constants.embeddings import EMBEDDING_STORES_SIZES, Vector
+
+from ._provisioning import borrow, ensure_brain_database, get_brain_pool
+
+
+logger = logging.getLogger(__name__)
+
+
+_STORE_NAME_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def string_to_int64(s: str) -> int:
+ sha256 = hashlib.sha256(s.encode()).digest()
+ return int.from_bytes(sha256[:8], byteorder="big") % (2**63)
+
+
+def _to_int_id(value: Any) -> int:
+ if isinstance(value, int):
+ return value
+ if isinstance(value, str):
+ try:
+ return int(value)
+ except ValueError:
+ return string_to_int64(value)
+ return string_to_int64(str(value))
+
+
+def _safe_store(store: str) -> str:
+ if not _STORE_NAME_RE.match(store):
+ raise ValueError(f"Invalid store name: {store}")
+ return store
+
+
+def _table_name(store: str) -> str:
+ return f"vectors_{_safe_store(store)}"
+
+
+def _vector_index_ddl(table: str, dimension: int) -> str:
+ dim = int(dimension)
+ if dim > 2000:
+ return ""
+ return f"""
+ CREATE INDEX IF NOT EXISTS idx_{table}_embeddings
+ ON {table} USING hnsw (embeddings vector_cosine_ops);
+ """
+
+
+def _table_vector_dimension(cur: psycopg2.extensions.cursor, table: str) -> Optional[int]:
+ cur.execute(
+ """
+ SELECT a.atttypmod
+ FROM pg_attribute a
+ JOIN pg_class c ON a.attrelid = c.oid
+ JOIN pg_namespace n ON c.relnamespace = n.oid
+ WHERE c.relname = %s
+ AND a.attname = 'embeddings'
+ AND NOT a.attisdropped
+ AND n.nspname = current_schema()
+ """,
+ (table,),
+ )
+ row = cur.fetchone()
+ if not row or row[0] is None or row[0] < 1:
+ return None
+ return int(row[0])
+
+
+class PostgreSQLVectorStoreClient(VectorStoreClient):
+ """
+ Vector store backed by PostgreSQL with the pgvector extension.
+
+ Each brain owns its own database (`brain_<sanitized_id>`); per-store tables
+ live inside that database with no `brain_id` column. The `vector` extension
+ is enabled lazily, once per brain database.
+ """
+
+ def __init__(self):
+ self._lock = threading.RLock()
+ self._brain_extensions_ready: set[str] = set()
+ self._initialized_stores: set[str] = set()
+
+ @contextmanager
+ def _connection(self, brain_id: str) -> Iterator[psycopg2.extensions.connection]:
+ self._ensure_extension(brain_id)
+ with borrow(get_brain_pool(brain_id)) as conn:
+ register_vector(conn)
+ yield conn
+
+ def _ensure_extension(self, brain_id: str) -> None:
+ if brain_id in self._brain_extensions_ready:
+ return
+ with self._lock:
+ if brain_id in self._brain_extensions_ready:
+ return
+ ensure_brain_database(brain_id)
+ with borrow(get_brain_pool(brain_id)) as conn:
+ with conn.cursor() as cur:
+ cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
+ conn.commit()
+ self._brain_extensions_ready.add(brain_id)
+
+ def _ensure_store(self, store: str, brain_id: str) -> None:
+ if store not in EMBEDDING_STORES_SIZES:
+ raise ValueError(f"Store {store} not available")
+ key = f"{brain_id}:{store}"
+ if key in self._initialized_stores:
+ return
+ with self._lock:
+ if key in self._initialized_stores:
+ return
+ dimension = EMBEDDING_STORES_SIZES[store]
+ table = _table_name(store)
+ ddl = f"""
+ CREATE TABLE IF NOT EXISTS {table} (
+ id BIGINT PRIMARY KEY,
+ uuid TEXT NOT NULL,
+ embeddings vector({dimension}),
+ metadata JSONB NOT NULL DEFAULT '{{}}'::jsonb
+ );
+ CREATE INDEX IF NOT EXISTS idx_{table}_uuid
+ ON {table} (uuid);
+ {_vector_index_ddl(table, dimension)}
+ """
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ existing_dim = _table_vector_dimension(cur, table)
+ if existing_dim is not None and existing_dim != dimension:
+ logger.warning(
+ "Recreating %s for brain %s: vector dimension %s -> %s",
+ table,
+ brain_id,
+ existing_dim,
+ dimension,
+ )
+ cur.execute(f"DROP TABLE IF EXISTS {table} CASCADE")
+ cur.execute(ddl)
+ conn.commit()
+ self._initialized_stores.add(key)
+
+ def add_vectors(
+ self, vectors: list[Vector], store: str, brain_id: str
+ ) -> list[str]:
+ if not vectors:
+ return []
+ self._ensure_store(store, brain_id)
+ table = _table_name(store)
+ rows = []
+ ids: list[int] = []
+ for vector in vectors:
+ int_id = string_to_int64(vector.id)
+ ids.append(int_id)
+ metadata = dict(vector.metadata or {})
+ metadata.pop("id", None)
+ metadata.pop("embeddings", None)
+ metadata.pop("distance", None)
+ rows.append(
+ (
+ int_id,
+ vector.id,
+ vector.embeddings,
+ json.dumps(metadata, default=str),
+ )
+ )
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ psycopg2.extras.execute_values(
+ cur,
+ f"""
+ INSERT INTO {table}
+ (id, uuid, embeddings, metadata)
+ VALUES %s
+ ON CONFLICT (id) DO UPDATE SET
+ uuid = EXCLUDED.uuid,
+ embeddings = EXCLUDED.embeddings,
+ metadata = EXCLUDED.metadata
+ """,
+ rows,
+ template="(%s, %s, %s, %s::jsonb)",
+ )
+ conn.commit()
+ return ids
+
+ def search_vectors(
+ self, data_vector: list[float], brain_id: str, store: str, k: int = 10
+ ) -> list[Vector]:
+ self._ensure_store(store, brain_id)
+ table = _table_name(store)
+ with self._connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT id, uuid, metadata,
+ (embeddings <=> %s::vector) AS distance
+ FROM {table}
+ ORDER BY embeddings <=> %s::vector
+ LIMIT %s
+ """,
+ (data_vector, data_vector, k),
+ )
+ rows = cur.fetchall()
+ results = [
+ Vector(
+ id=str(row["id"]),
+ metadata=dict(row["metadata"] or {}),
+ distance=float(row["distance"]),
+ )
+ for row in rows
+ ]
+ results.sort(key=lambda x: x.distance)
+ return results
+
+ def get_by_ids(self, ids: list[str], store: str, brain_id: str) -> list[Vector]:
+ if not ids:
+ return []
+ self._ensure_store(store, brain_id)
+ table = _table_name(store)
+ int_ids = [_to_int_id(i) for i in ids]
+ with self._connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT id, uuid, embeddings, metadata
+ FROM {table}
+ WHERE id = ANY(%s)
+ """,
+ (int_ids,),
+ )
+ rows = cur.fetchall()
+ results: list[Vector] = []
+ for row in rows:
+ embeddings = row["embeddings"]
+ if embeddings is not None and not isinstance(embeddings, list):
+ embeddings = list(embeddings)
+ results.append(
+ Vector(
+ id=row["uuid"] or str(row["id"]),
+ embeddings=embeddings,
+ metadata=dict(row["metadata"] or {}),
+ )
+ )
+ return results
+
+ def search_similar_by_ids(
+ self,
+ vector_ids: list[str],
+ brain_id: str,
+ store: str,
+ min_similarity: float,
+ limit: int = 10,
+ ) -> dict[str, list[Vector]]:
+ if not vector_ids:
+ return {}
+ self._ensure_store(store, brain_id)
+ table = _table_name(store)
+ int_ids = [_to_int_id(i) for i in vector_ids]
+
+ with self._connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ cur.execute(
+ f"""
+ SELECT id, uuid, embeddings
+ FROM {table}
+ WHERE id = ANY(%s)
+ """,
+ (int_ids,),
+ )
+ origin_rows = cur.fetchall()
+ embeddings_by_id: dict[int, list[float]] = {}
+ for row in origin_rows:
+ embedding = row["embeddings"]
+ if embedding is None:
+ continue
+ if not isinstance(embedding, list):
+ embedding = list(embedding)
+ embeddings_by_id[row["id"]] = embedding
+
+ out: dict[str, list[Vector]] = {str(v_id): [] for v_id in vector_ids}
+ if not embeddings_by_id:
+ return out
+
+ fetch_limit = max(limit * 5, limit) + 1
+ with self._connection(brain_id) as conn:
+ with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+ for origin_id, embedding in embeddings_by_id.items():
+ cur.execute(
+ f"""
+ SELECT id, uuid, metadata,
+ (embeddings <=> %s::vector) AS distance
+ FROM {table}
+ ORDER BY embeddings <=> %s::vector
+ LIMIT %s
+ """,
+ (embedding, embedding, fetch_limit),
+ )
+ rows = cur.fetchall()
+ collected: list[Vector] = []
+ for row in rows:
+ if row["id"] == origin_id:
+ continue
+ distance = float(row["distance"])
+ similarity = 1.0 - distance
+ if similarity < min_similarity:
+ continue
+ collected.append(
+ Vector(
+ id=str(row["id"]),
+ metadata=dict(row["metadata"] or {}),
+ distance=distance,
+ )
+ )
+ if len(collected) >= limit:
+ break
+ out[str(origin_id)] = collected
+ return out
+
+ def remove_vectors(self, ids: list[str], store: str, brain_id: str) -> None:
+ if not ids:
+ return
+ self._ensure_store(store, brain_id)
+ table = _table_name(store)
+ int_ids = [_to_int_id(i) for i in ids]
+ try:
+ with self._connection(brain_id) as conn:
+ with conn.cursor() as cur:
+ cur.execute(
+ f"""
+ DELETE FROM {table}
+ WHERE id = ANY(%s)
+ """,
+ (int_ids,),
+ )
+ conn.commit()
+ except Exception as exc:
+ print(f"[PostgreSQLVectorStore] Failed to remove vectors from {store}: {exc}")
+
+
+_postgresql_vector_store_client: Optional[PostgreSQLVectorStoreClient] = None
+
+
+def get_postgresql_vector_store_client() -> PostgreSQLVectorStoreClient:
+ global _postgresql_vector_store_client
+ if _postgresql_vector_store_client is None:
+ _postgresql_vector_store_client = PostgreSQLVectorStoreClient()
+ return _postgresql_vector_store_client
diff --git a/src/workers/tasks/ingestion.py b/src/workers/tasks/ingestion.py
index aa4e395..df4128a 100644
--- a/src/workers/tasks/ingestion.py
+++ b/src/workers/tasks/ingestion.py
@@ -142,6 +142,7 @@ def ingest_data(self, args: dict):
vector_store_adapter.add_vectors(
[text_chunk_vector],
"data",
+ brain_id=payload.brain_id,
)
if config.pipeline_mode == "lightweight":
@@ -828,7 +829,15 @@ def ingest_file(self, content_b64: str, filename: str, brain_id: str):
ingest_data task per page.
"""
from celery.exceptions import OperationalError
- from docling.document_converter import DocumentConverter
+ try:
+ from docling.document_converter import DocumentConverter
+ except ImportError as exc:
+ raise RuntimeError(
+ "OCR_MODE=docling requires the 'docling-ocr' optional dependency group. "
+ "Install it with: `python scripts/install_extras.py docling-ocr` "
+ "(or `make install-extras`). "
+ "Alternatively set OCR_MODE=docparser in your .env to use the remote OCR pipeline."
+ ) from exc
cache_adapter.set(
key=f"task:{self.request.id}",
diff --git a/tui/README.md b/tui/README.md
new file mode 100644
index 0000000..9a1b0b9
--- /dev/null
+++ b/tui/README.md
@@ -0,0 +1,84 @@
+# brainapi
+
+Interactive installer and runtime CLI for [BrainAPI](https://github.com/Lumen-Labs/brainapi2).
+
+## Install
+
+```bash
+npm install -g brainapi
+```
+
+This puts a `brainapi` binary on your `$PATH`.
+
+## Quick start
+
+```bash
+brainapi init # clone the project, set up a Python venv, configure services
+brainapi start # start docker compose services + run the API
+brainapi doctor # check Python, Docker, Ollama, and configured services
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `brainapi init` | Full bootstrap: clone the repo, create a Python venv, install deps, and run the interactive setup. |
+| `brainapi start` | Start docker compose containers for the chosen services and launch the API. |
+| `brainapi config` | Re-run the interactive flow and rewrite `.env`. |
+| `brainapi doctor` | Check that Python, Docker, Ollama, GCP credentials, and configured services are reachable. |
+| `brainapi update` | `git pull` the project and `pip install -e .` again. |
+
+### `brainapi start` options
+
+| Option | Description |
+| --- | --- |
+| `--pipeline accurate\|lightweight` | Set `PIPELINE_MODE` in `~/.brainapi/source/.env` before start (accurate = full pipeline; lightweight = faster ingestion). |
+
+## Where things live
+
+- Source: `~/.brainapi/source/`
+- Python venv: `~/.brainapi/source/.venv/`
+- Env file: `~/.brainapi/source/.env`
+- Install state: `~/.brainapi/state.json`
+
+## Configuration
+
+The interactive flow asks:
+
+1. Use default settings? (NetworkX + Postgres + pgvector + remote GCP Vertex)
+2. Otherwise: Vector DB → Data DB → Graph DB → Models mode
+3. For `remote` models mode: pick provider, then provide GCP credentials, project, and model names
+4. For `local` models mode: probe Ollama, wait for it to start, then verify pulled models
+5. Connection details for only the services you actually selected
+6. `BRAINPAT_TOKEN` (generate or paste)
+7. Optionally start the docker compose containers now
+
+If Python (>=3.11) or Docker is missing, the TUI walks you through installing them with platform-aware commands and retries detection automatically.
+
+## Development
+
+```bash
+cd tui
+npm install
+npm run dev # builds in watch mode
+node dist/index.js init # try it
+```
+
+### Publishing
+
+```bash
+npm version <patch|minor|major>
+npm publish
+```
+
+`prepublishOnly` runs the build automatically so the published tarball always contains `dist/`. Only the `dist/`, `README.md`, and `LICENSE` files are included (see the `files` field in `package.json`).
+
+If someone runs any command before `brainapi init` (e.g. `brainapi doctor` or `brainapi start`), the CLI prints a notice and runs `init` first.
+
+## Environment overrides
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `BRAINAPI_REPO_URL` | `https://github.com/Lumen-Labs/brainapi2.git` | The git repo cloned on `init`. |
+| `BRAINAPI_HOME` | `$HOME/.brainapi` | Where the source and state live. |
+| `BRAINAPI_BRANCH` | `main` | Branch to checkout after cloning. |
diff --git a/tui/package-lock.json b/tui/package-lock.json
new file mode 100644
index 0000000..574fcc5
--- /dev/null
+++ b/tui/package-lock.json
@@ -0,0 +1,1877 @@
+{
+ "name": "brainapi",
+ "version": "0.1.0",
+ "lockfileVersion": 3,
+ "requires": true,
+ "packages": {
+ "": {
+ "name": "brainapi",
+ "version": "0.1.0",
+ "license": "MIT",
+ "dependencies": {
+ "@clack/prompts": "^0.7.0",
+ "execa": "^9.4.0",
+ "picocolors": "^1.1.0",
+ "simple-git": "^3.27.0"
+ },
+ "bin": {
+ "brainapi": "dist/index.js"
+ },
+ "devDependencies": {
+ "@types/node": "^22.7.4",
+ "tsup": "^8.3.0",
+ "typescript": "^5.6.2"
+ },
+ "engines": {
+ "node": ">=18.17"
+ }
+ },
+ "node_modules/@clack/core": {
+ "version": "0.3.5",
+ "resolved": "https://registry.npmjs.org/@clack/core/-/core-0.3.5.tgz",
+ "integrity": "sha512-5cfhQNH+1VQ2xLQlmzXMqUoiaH0lRBq9/CLW9lTyMbuKLC3+xEK01tHVvyut++mLOn5urSHmkm6I0Lg9MaJSTQ==",
+ "license": "MIT",
+ "dependencies": {
+ "picocolors": "^1.0.0",
+ "sisteransi": "^1.0.5"
+ }
+ },
+ "node_modules/@clack/prompts": {
+ "version": "0.7.0",
+ "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-0.7.0.tgz",
+ "integrity": "sha512-0MhX9/B4iL6Re04jPrttDm+BsP8y6mS7byuv0BvXgdXhbV5PdlsHt55dvNsuBCPZ7xq1oTAOOuotR9NFbQyMSA==",
+ "bundleDependencies": [
+ "is-unicode-supported"
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "@clack/core": "^0.3.3",
+ "is-unicode-supported": "*",
+ "picocolors": "^1.0.0",
+ "sisteransi": "^1.0.5"
+ }
+ },
+ "node_modules/@clack/prompts/node_modules/is-unicode-supported": {
+ "version": "1.3.0",
+ "inBundle": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/@esbuild/aix-ppc64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+ "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "aix"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+ "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+ "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/android-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+ "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+ "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/darwin-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+ "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+ "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/freebsd-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+ "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+ "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+ "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ia32": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+ "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-loong64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+ "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-mips64el": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+ "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+ "cpu": [
+ "mips64el"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-ppc64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+ "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-riscv64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+ "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-s390x": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+ "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/linux-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+ "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+ "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/netbsd-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+ "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "netbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+ "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openbsd-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+ "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/openharmony-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+ "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/sunos-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+ "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "sunos"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-arm64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+ "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-ia32": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+ "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@esbuild/win32-x64": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+ "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ],
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/@jridgewell/gen-mapping": {
+ "version": "0.3.13",
+ "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+ "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@jridgewell/sourcemap-codec": "^1.5.0",
+ "@jridgewell/trace-mapping": "^0.3.24"
+ }
+ },
+ "node_modules/@jridgewell/resolve-uri": {
+ "version": "3.1.2",
+ "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+ "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=6.0.0"
+ }
+ },
+ "node_modules/@jridgewell/sourcemap-codec": {
+ "version": "1.5.5",
+ "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+ "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@jridgewell/trace-mapping": {
+ "version": "0.3.31",
+ "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+ "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@jridgewell/resolve-uri": "^3.1.0",
+ "@jridgewell/sourcemap-codec": "^1.4.14"
+ }
+ },
+ "node_modules/@kwsites/file-exists": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/@kwsites/file-exists/-/file-exists-1.1.1.tgz",
+ "integrity": "sha512-m9/5YGR18lIwxSFDwfE3oA7bWuq9kdau6ugN4H2rJeyhFQZcG9AgSHkQtSD15a8WvTgfz9aikZMrKPHvbpqFiw==",
+ "license": "MIT",
+ "dependencies": {
+ "debug": "^4.1.1"
+ }
+ },
+ "node_modules/@kwsites/promise-deferred": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/@kwsites/promise-deferred/-/promise-deferred-1.1.1.tgz",
+ "integrity": "sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==",
+ "license": "MIT"
+ },
+ "node_modules/@rollup/rollup-android-arm-eabi": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
+ "integrity": "sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ]
+ },
+ "node_modules/@rollup/rollup-android-arm64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.4.tgz",
+ "integrity": "sha512-GxxTKApUpzRhof7poWvCJHRF51C67u1R7D6DiluBE8wKU1u5GWE8t+v81JvJYtbawoBFX1hLv5Ei4eVjkWokaw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "android"
+ ]
+ },
+ "node_modules/@rollup/rollup-darwin-arm64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.4.tgz",
+ "integrity": "sha512-tua0TaJxMOB1R0V0RS1jFZ/RpURFDJIOR2A6jWwQeawuFyS4gBW+rntLRaQd0EQ4bd6Vp44Z2rXW+YYDBsj6IA==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ]
+ },
+ "node_modules/@rollup/rollup-darwin-x64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.4.tgz",
+ "integrity": "sha512-CSKq7MsP+5PFIcydhAiR1K0UhEI1A2jWXVKHPCBZ151yOutENwvnPocgVHkivu2kviURtCEB6zUQw0vs8RrhMg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ]
+ },
+ "node_modules/@rollup/rollup-freebsd-arm64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.4.tgz",
+ "integrity": "sha512-+O8OkVdyvXMtJEciu2wS/pzm1IxntEEQx3z5TAVy4l32G0etZn+RsA48ARRrFm6Ri8fvqPQfgrvNxSjKAbnd3g==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ]
+ },
+ "node_modules/@rollup/rollup-freebsd-x64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.4.tgz",
+ "integrity": "sha512-Iw3oMskH3AfNuhU0MSN7vNbdi4me/NiYo2azqPz/Le16zHSa+3RRmliCMWWQmh4lcndccU40xcJuTYJZxNo/lw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "freebsd"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.4.tgz",
+ "integrity": "sha512-EIPRXTVQpHyF8WOo219AD2yEltPehLTcTMz2fn6JsatLYSzQf00hj3rulF+yauOlF9/FtM2WpkT/hJh/KJFGhA==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.4.tgz",
+ "integrity": "sha512-J3Yh9PzzF1Ovah2At+lHiGQdsYgArxBbXv/zHfSyaiFQEqvNv7DcW98pCrmdjCZBrqBiKrKKe2V+aaSGWuBe/w==",
+ "cpu": [
+ "arm"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-arm64-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.4.tgz",
+ "integrity": "sha512-BFDEZMYfUvLn37ONE1yMBojPxnMlTFsdyNoqncT0qFq1mAfllL+ATMMJd8TeuVMiX84s1KbcxcZbXInmcO2mRg==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-arm64-musl": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.4.tgz",
+ "integrity": "sha512-pc9EYOSlOgdQ2uPl1o9PF6/kLSgaUosia7gOuS8mB69IxJvlclko1MECXysjs5ryez1/5zjYqx3+xYU0TU6R1A==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-loong64-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.4.tgz",
+ "integrity": "sha512-NxnomyxYerDh5n4iLrNa+sH+Z+U4BMEE46V2PgQ/hoB909i8gV1M5wPojWg9fk1jWpO3IQnOs20K4wyZuFLEFQ==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-loong64-musl": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.4.tgz",
+ "integrity": "sha512-nbJnQ8a3z1mtmrwImCYhc6BGpThAyYVRQxw9uKSKG4wR6aAYno9sVjJ0zaZcW9BPJX1GbrDPf+SvdWjgTuDmnw==",
+ "cpu": [
+ "loong64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.4.tgz",
+ "integrity": "sha512-2EU6acNrQLd8tYvo/LXW535wupT3m6fo7HKo6lr7ktQoItxTyOL1ZCR/GfGCuXl2vR+zmfI6eRXkSemafv+iVg==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-ppc64-musl": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.4.tgz",
+ "integrity": "sha512-WeBtoMuaMxiiIrO2IYP3xs6GMWkJP2C0EoT8beTLkUPmzV1i/UcOSVw1d5r9KBODtHKilG5yFxsGRnBbK3wJ4A==",
+ "cpu": [
+ "ppc64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.4.tgz",
+ "integrity": "sha512-FJHFfqpKUI3A10WrWKiFbBZ7yVbGT4q4B5o1qKFFojqpaYoh9LrQgqWCmmcxQzVSXYtyB5bzkXrYzlHTs21MYA==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-riscv64-musl": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.4.tgz",
+ "integrity": "sha512-mcEl6CUT5IAUmQf1m9FYSmVqCJlpQ8r8eyftFUHG8i9OhY7BkBXSUdnLH5DOf0wCOjcP9v/QO93zpmF1SptCCw==",
+ "cpu": [
+ "riscv64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-s390x-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.4.tgz",
+ "integrity": "sha512-ynt3JxVd2w2buzoKDWIyiV1pJW93xlQic1THVLXilz429oijRpSHivZAgp65KBu+cMcgf1eVVjdnTLvPxgCuoQ==",
+ "cpu": [
+ "s390x"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-x64-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.4.tgz",
+ "integrity": "sha512-Boiz5+MsaROEWDf+GGEwF8VMHGhlUoQMtIPjOgA5fv4osupqTVnJteQNKJwUcnUog2G55jYXH7KZFFiJe0TEzQ==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-linux-x64-musl": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.4.tgz",
+ "integrity": "sha512-+qfSY27qIrFfI/Hom04KYFw3GKZSGU4lXus51wsb5EuySfFlWRwjkKWoE9emgRw/ukoT4Udsj4W/+xxG8VbPKg==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "linux"
+ ]
+ },
+ "node_modules/@rollup/rollup-openbsd-x64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.4.tgz",
+ "integrity": "sha512-VpTfOPHgVXEBeeR8hZ2O0F3aSso+JDWqTWmTmzcQKted54IAdUVbxE+j/MVxUsKa8L20HJhv3vUezVPoquqWjA==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openbsd"
+ ]
+ },
+ "node_modules/@rollup/rollup-openharmony-arm64": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.4.tgz",
+ "integrity": "sha512-IPOsh5aRYuLv/nkU51X10Bf75Bsf6+gZdx1X+QP5QM6lIJFHHqbHLG0uJn/hWthzo13UAc2umiUorqZy3axoZg==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "openharmony"
+ ]
+ },
+ "node_modules/@rollup/rollup-win32-arm64-msvc": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.4.tgz",
+ "integrity": "sha512-4QzE9E81OohJ/HKzHhsqU+zcYYojVOXlFMs1DdyMT6qXl/niOH7AVElmmEdUNHHS/oRkc++d5k6Vy85zFs0DEw==",
+ "cpu": [
+ "arm64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ]
+ },
+ "node_modules/@rollup/rollup-win32-ia32-msvc": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.4.tgz",
+ "integrity": "sha512-zTPgT1YuHHcd+Tmx7h8aml0FWFVelV5N54oHow9SLj+GfoDy/huQ+UV396N/C7KpMDMiPspRktzM1/0r1usYEA==",
+ "cpu": [
+ "ia32"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ]
+ },
+ "node_modules/@rollup/rollup-win32-x64-gnu": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.4.tgz",
+ "integrity": "sha512-DRS4G7mi9lJxqEDezIkKCaUIKCrLUUDCUaCsTPCi/rtqaC6D/jjwslMQyiDU50Ka0JKpeXeRBFBAXwArY52vBw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ]
+ },
+ "node_modules/@rollup/rollup-win32-x64-msvc": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.4.tgz",
+ "integrity": "sha512-QVTUovf40zgTqlFVrKA1uXMVvU2QWEFWfAH8Wdc48IxLvrJMQVMBRjuQyUpzZCDkakImib9eVazbWlC6ksWtJw==",
+ "cpu": [
+ "x64"
+ ],
+ "dev": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "win32"
+ ]
+ },
+ "node_modules/@sec-ant/readable-stream": {
+ "version": "0.4.1",
+ "resolved": "https://registry.npmjs.org/@sec-ant/readable-stream/-/readable-stream-0.4.1.tgz",
+ "integrity": "sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==",
+ "license": "MIT"
+ },
+ "node_modules/@simple-git/args-pathspec": {
+ "version": "1.0.3",
+ "resolved": "https://registry.npmjs.org/@simple-git/args-pathspec/-/args-pathspec-1.0.3.tgz",
+ "integrity": "sha512-ngJMaHlsWDTfjyq9F3VIQ8b7NXbBLq5j9i5bJ6XLYtD6qlDXT7fdKY2KscWWUF8t18xx052Y/PUO1K1TRc9yKA==",
+ "license": "MIT"
+ },
+ "node_modules/@simple-git/argv-parser": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/@simple-git/argv-parser/-/argv-parser-1.1.1.tgz",
+ "integrity": "sha512-Q9lBcfQ+VQCpQqGJFHe5yooOS5hGdLFFbJ5R+R5aDsnkPCahtn1hSkMcORX65J2Z5lxSkD0lQorMsncuBQxYUw==",
+ "license": "MIT",
+ "dependencies": {
+ "@simple-git/args-pathspec": "^1.0.3"
+ }
+ },
+ "node_modules/@sindresorhus/merge-streams": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz",
+ "integrity": "sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/@types/estree": {
+ "version": "1.0.8",
+ "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+ "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@types/node": {
+ "version": "22.19.19",
+ "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz",
+ "integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "undici-types": "~6.21.0"
+ }
+ },
+ "node_modules/acorn": {
+ "version": "8.16.0",
+ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
+ "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "acorn": "bin/acorn"
+ },
+ "engines": {
+ "node": ">=0.4.0"
+ }
+ },
+ "node_modules/any-promise": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/any-promise/-/any-promise-1.3.0.tgz",
+ "integrity": "sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/bundle-require": {
+ "version": "5.1.0",
+ "resolved": "https://registry.npmjs.org/bundle-require/-/bundle-require-5.1.0.tgz",
+ "integrity": "sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "load-tsconfig": "^0.2.3"
+ },
+ "engines": {
+ "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+ },
+ "peerDependencies": {
+ "esbuild": ">=0.18"
+ }
+ },
+ "node_modules/cac": {
+ "version": "6.7.14",
+ "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
+ "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/chokidar": {
+ "version": "4.0.3",
+ "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz",
+ "integrity": "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "readdirp": "^4.0.1"
+ },
+ "engines": {
+ "node": ">= 14.16.0"
+ },
+ "funding": {
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
+ "node_modules/commander": {
+ "version": "4.1.1",
+ "resolved": "https://registry.npmjs.org/commander/-/commander-4.1.1.tgz",
+ "integrity": "sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/confbox": {
+ "version": "0.1.8",
+ "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.1.8.tgz",
+ "integrity": "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/consola": {
+ "version": "3.4.2",
+ "resolved": "https://registry.npmjs.org/consola/-/consola-3.4.2.tgz",
+ "integrity": "sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": "^14.18.0 || >=16.10.0"
+ }
+ },
+ "node_modules/cross-spawn": {
+ "version": "7.0.6",
+ "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+ "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+ "license": "MIT",
+ "dependencies": {
+ "path-key": "^3.1.0",
+ "shebang-command": "^2.0.0",
+ "which": "^2.0.1"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
+ "node_modules/debug": {
+ "version": "4.4.3",
+ "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+ "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+ "license": "MIT",
+ "dependencies": {
+ "ms": "^2.1.3"
+ },
+ "engines": {
+ "node": ">=6.0"
+ },
+ "peerDependenciesMeta": {
+ "supports-color": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/esbuild": {
+ "version": "0.27.7",
+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
+ "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "bin": {
+ "esbuild": "bin/esbuild"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "optionalDependencies": {
+ "@esbuild/aix-ppc64": "0.27.7",
+ "@esbuild/android-arm": "0.27.7",
+ "@esbuild/android-arm64": "0.27.7",
+ "@esbuild/android-x64": "0.27.7",
+ "@esbuild/darwin-arm64": "0.27.7",
+ "@esbuild/darwin-x64": "0.27.7",
+ "@esbuild/freebsd-arm64": "0.27.7",
+ "@esbuild/freebsd-x64": "0.27.7",
+ "@esbuild/linux-arm": "0.27.7",
+ "@esbuild/linux-arm64": "0.27.7",
+ "@esbuild/linux-ia32": "0.27.7",
+ "@esbuild/linux-loong64": "0.27.7",
+ "@esbuild/linux-mips64el": "0.27.7",
+ "@esbuild/linux-ppc64": "0.27.7",
+ "@esbuild/linux-riscv64": "0.27.7",
+ "@esbuild/linux-s390x": "0.27.7",
+ "@esbuild/linux-x64": "0.27.7",
+ "@esbuild/netbsd-arm64": "0.27.7",
+ "@esbuild/netbsd-x64": "0.27.7",
+ "@esbuild/openbsd-arm64": "0.27.7",
+ "@esbuild/openbsd-x64": "0.27.7",
+ "@esbuild/openharmony-arm64": "0.27.7",
+ "@esbuild/sunos-x64": "0.27.7",
+ "@esbuild/win32-arm64": "0.27.7",
+ "@esbuild/win32-ia32": "0.27.7",
+ "@esbuild/win32-x64": "0.27.7"
+ }
+ },
+ "node_modules/execa": {
+ "version": "9.6.1",
+ "resolved": "https://registry.npmjs.org/execa/-/execa-9.6.1.tgz",
+ "integrity": "sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==",
+ "license": "MIT",
+ "dependencies": {
+ "@sindresorhus/merge-streams": "^4.0.0",
+ "cross-spawn": "^7.0.6",
+ "figures": "^6.1.0",
+ "get-stream": "^9.0.0",
+ "human-signals": "^8.0.1",
+ "is-plain-obj": "^4.1.0",
+ "is-stream": "^4.0.1",
+ "npm-run-path": "^6.0.0",
+ "pretty-ms": "^9.2.0",
+ "signal-exit": "^4.1.0",
+ "strip-final-newline": "^4.0.0",
+ "yoctocolors": "^2.1.1"
+ },
+ "engines": {
+ "node": "^18.19.0 || >=20.5.0"
+ },
+ "funding": {
+ "url": "https://github.com/sindresorhus/execa?sponsor=1"
+ }
+ },
+ "node_modules/fdir": {
+ "version": "6.5.0",
+ "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+ "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "peerDependencies": {
+ "picomatch": "^3 || ^4"
+ },
+ "peerDependenciesMeta": {
+ "picomatch": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/figures": {
+ "version": "6.1.0",
+ "resolved": "https://registry.npmjs.org/figures/-/figures-6.1.0.tgz",
+ "integrity": "sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg==",
+ "license": "MIT",
+ "dependencies": {
+ "is-unicode-supported": "^2.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/fix-dts-default-cjs-exports": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/fix-dts-default-cjs-exports/-/fix-dts-default-cjs-exports-1.0.1.tgz",
+ "integrity": "sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "magic-string": "^0.30.17",
+ "mlly": "^1.7.4",
+ "rollup": "^4.34.8"
+ }
+ },
+ "node_modules/fsevents": {
+ "version": "2.3.3",
+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+ "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+ "dev": true,
+ "hasInstallScript": true,
+ "license": "MIT",
+ "optional": true,
+ "os": [
+ "darwin"
+ ],
+ "engines": {
+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+ }
+ },
+ "node_modules/get-stream": {
+ "version": "9.0.1",
+ "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-9.0.1.tgz",
+ "integrity": "sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA==",
+ "license": "MIT",
+ "dependencies": {
+ "@sec-ant/readable-stream": "^0.4.1",
+ "is-stream": "^4.0.1"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/human-signals": {
+ "version": "8.0.1",
+ "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-8.0.1.tgz",
+ "integrity": "sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==",
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=18.18.0"
+ }
+ },
+ "node_modules/is-plain-obj": {
+ "version": "4.1.0",
+ "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz",
+ "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/is-stream": {
+ "version": "4.0.1",
+ "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-4.0.1.tgz",
+ "integrity": "sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/is-unicode-supported": {
+ "version": "2.1.0",
+ "resolved": "https://registry.npmjs.org/is-unicode-supported/-/is-unicode-supported-2.1.0.tgz",
+ "integrity": "sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/isexe": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+ "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+ "license": "ISC"
+ },
+ "node_modules/joycon": {
+ "version": "3.1.1",
+ "resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz",
+ "integrity": "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/lilconfig": {
+ "version": "3.1.3",
+ "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz",
+ "integrity": "sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=14"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/antonk52"
+ }
+ },
+ "node_modules/lines-and-columns": {
+ "version": "1.2.4",
+ "resolved": "https://registry.npmjs.org/lines-and-columns/-/lines-and-columns-1.2.4.tgz",
+ "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/load-tsconfig": {
+ "version": "0.2.5",
+ "resolved": "https://registry.npmjs.org/load-tsconfig/-/load-tsconfig-0.2.5.tgz",
+ "integrity": "sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+ }
+ },
+ "node_modules/magic-string": {
+ "version": "0.30.21",
+ "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+ "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@jridgewell/sourcemap-codec": "^1.5.5"
+ }
+ },
+ "node_modules/mlly": {
+ "version": "1.8.2",
+ "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.2.tgz",
+ "integrity": "sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "acorn": "^8.16.0",
+ "pathe": "^2.0.3",
+ "pkg-types": "^1.3.1",
+ "ufo": "^1.6.3"
+ }
+ },
+ "node_modules/ms": {
+ "version": "2.1.3",
+ "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+ "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+ "license": "MIT"
+ },
+ "node_modules/mz": {
+ "version": "2.7.0",
+ "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz",
+ "integrity": "sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "any-promise": "^1.0.0",
+ "object-assign": "^4.0.1",
+ "thenify-all": "^1.0.0"
+ }
+ },
+ "node_modules/npm-run-path": {
+ "version": "6.0.0",
+ "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-6.0.0.tgz",
+ "integrity": "sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==",
+ "license": "MIT",
+ "dependencies": {
+ "path-key": "^4.0.0",
+ "unicorn-magic": "^0.3.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/npm-run-path/node_modules/path-key": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz",
+ "integrity": "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/object-assign": {
+ "version": "4.1.1",
+ "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+ "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/parse-ms": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/parse-ms/-/parse-ms-4.0.0.tgz",
+ "integrity": "sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/path-key": {
+ "version": "3.1.1",
+ "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+ "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/pathe": {
+ "version": "2.0.3",
+ "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+ "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/picocolors": {
+ "version": "1.1.1",
+ "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+ "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+ "license": "ISC"
+ },
+ "node_modules/picomatch": {
+ "version": "4.0.4",
+ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+ "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=12"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/jonschlinkert"
+ }
+ },
+ "node_modules/pirates": {
+ "version": "4.0.7",
+ "resolved": "https://registry.npmjs.org/pirates/-/pirates-4.0.7.tgz",
+ "integrity": "sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/pkg-types": {
+ "version": "1.3.1",
+ "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz",
+ "integrity": "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "confbox": "^0.1.8",
+ "mlly": "^1.7.4",
+ "pathe": "^2.0.1"
+ }
+ },
+ "node_modules/postcss-load-config": {
+ "version": "6.0.1",
+ "resolved": "https://registry.npmjs.org/postcss-load-config/-/postcss-load-config-6.0.1.tgz",
+ "integrity": "sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "opencollective",
+ "url": "https://opencollective.com/postcss/"
+ },
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/ai"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "lilconfig": "^3.1.1"
+ },
+ "engines": {
+ "node": ">= 18"
+ },
+ "peerDependencies": {
+ "jiti": ">=1.21.0",
+ "postcss": ">=8.0.9",
+ "tsx": "^4.8.1",
+ "yaml": "^2.4.2"
+ },
+ "peerDependenciesMeta": {
+ "jiti": {
+ "optional": true
+ },
+ "postcss": {
+ "optional": true
+ },
+ "tsx": {
+ "optional": true
+ },
+ "yaml": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/pretty-ms": {
+ "version": "9.3.0",
+ "resolved": "https://registry.npmjs.org/pretty-ms/-/pretty-ms-9.3.0.tgz",
+ "integrity": "sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ==",
+ "license": "MIT",
+ "dependencies": {
+ "parse-ms": "^4.0.0"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/readdirp": {
+ "version": "4.1.2",
+ "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz",
+ "integrity": "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 14.18.0"
+ },
+ "funding": {
+ "type": "individual",
+ "url": "https://paulmillr.com/funding/"
+ }
+ },
+ "node_modules/resolve-from": {
+ "version": "5.0.0",
+ "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz",
+ "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/rollup": {
+ "version": "4.60.4",
+ "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
+ "integrity": "sha512-WHeFSbZYsPu3+bLoNRUuAO+wavNlocOPf3wSHTP7hcFKVnJeWsYlCDbr3mTS14FCizf9ccIxXA8sGL8zKeQN3g==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/estree": "1.0.8"
+ },
+ "bin": {
+ "rollup": "dist/bin/rollup"
+ },
+ "engines": {
+ "node": ">=18.0.0",
+ "npm": ">=8.0.0"
+ },
+ "optionalDependencies": {
+ "@rollup/rollup-android-arm-eabi": "4.60.4",
+ "@rollup/rollup-android-arm64": "4.60.4",
+ "@rollup/rollup-darwin-arm64": "4.60.4",
+ "@rollup/rollup-darwin-x64": "4.60.4",
+ "@rollup/rollup-freebsd-arm64": "4.60.4",
+ "@rollup/rollup-freebsd-x64": "4.60.4",
+ "@rollup/rollup-linux-arm-gnueabihf": "4.60.4",
+ "@rollup/rollup-linux-arm-musleabihf": "4.60.4",
+ "@rollup/rollup-linux-arm64-gnu": "4.60.4",
+ "@rollup/rollup-linux-arm64-musl": "4.60.4",
+ "@rollup/rollup-linux-loong64-gnu": "4.60.4",
+ "@rollup/rollup-linux-loong64-musl": "4.60.4",
+ "@rollup/rollup-linux-ppc64-gnu": "4.60.4",
+ "@rollup/rollup-linux-ppc64-musl": "4.60.4",
+ "@rollup/rollup-linux-riscv64-gnu": "4.60.4",
+ "@rollup/rollup-linux-riscv64-musl": "4.60.4",
+ "@rollup/rollup-linux-s390x-gnu": "4.60.4",
+ "@rollup/rollup-linux-x64-gnu": "4.60.4",
+ "@rollup/rollup-linux-x64-musl": "4.60.4",
+ "@rollup/rollup-openbsd-x64": "4.60.4",
+ "@rollup/rollup-openharmony-arm64": "4.60.4",
+ "@rollup/rollup-win32-arm64-msvc": "4.60.4",
+ "@rollup/rollup-win32-ia32-msvc": "4.60.4",
+ "@rollup/rollup-win32-x64-gnu": "4.60.4",
+ "@rollup/rollup-win32-x64-msvc": "4.60.4",
+ "fsevents": "~2.3.2"
+ }
+ },
+ "node_modules/shebang-command": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+ "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+ "license": "MIT",
+ "dependencies": {
+ "shebang-regex": "^3.0.0"
+ },
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/shebang-regex": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+ "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=8"
+ }
+ },
+ "node_modules/signal-exit": {
+ "version": "4.1.0",
+ "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+ "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=14"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/isaacs"
+ }
+ },
+ "node_modules/simple-git": {
+ "version": "3.36.0",
+ "resolved": "https://registry.npmjs.org/simple-git/-/simple-git-3.36.0.tgz",
+ "integrity": "sha512-cGQjLjK8bxJw4QuYT7gxHw3/IouVESbhahSsHrX97MzCL1gu2u7oy38W6L2ZIGECEfIBG4BabsWDPjBxJENv9Q==",
+ "license": "MIT",
+ "dependencies": {
+ "@kwsites/file-exists": "^1.1.1",
+ "@kwsites/promise-deferred": "^1.1.1",
+ "@simple-git/args-pathspec": "^1.0.3",
+ "@simple-git/argv-parser": "^1.1.0",
+ "debug": "^4.4.0"
+ },
+ "funding": {
+ "type": "github",
+ "url": "https://github.com/steveukx/git-js?sponsor=1"
+ }
+ },
+ "node_modules/sisteransi": {
+ "version": "1.0.5",
+ "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
+ "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",
+ "license": "MIT"
+ },
+ "node_modules/source-map": {
+ "version": "0.7.6",
+ "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz",
+ "integrity": "sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "engines": {
+ "node": ">= 12"
+ }
+ },
+ "node_modules/strip-final-newline": {
+ "version": "4.0.0",
+ "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-4.0.0.tgz",
+ "integrity": "sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/sucrase": {
+ "version": "3.35.1",
+ "resolved": "https://registry.npmjs.org/sucrase/-/sucrase-3.35.1.tgz",
+ "integrity": "sha512-DhuTmvZWux4H1UOnWMB3sk0sbaCVOoQZjv8u1rDoTV0HTdGem9hkAZtl4JZy8P2z4Bg0nT+YMeOFyVr4zcG5Tw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@jridgewell/gen-mapping": "^0.3.2",
+ "commander": "^4.0.0",
+ "lines-and-columns": "^1.1.6",
+ "mz": "^2.7.0",
+ "pirates": "^4.0.1",
+ "tinyglobby": "^0.2.11",
+ "ts-interface-checker": "^0.1.9"
+ },
+ "bin": {
+ "sucrase": "bin/sucrase",
+ "sucrase-node": "bin/sucrase-node"
+ },
+ "engines": {
+ "node": ">=16 || 14 >=14.17"
+ }
+ },
+ "node_modules/thenify": {
+ "version": "3.3.1",
+ "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz",
+ "integrity": "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "any-promise": "^1.0.0"
+ }
+ },
+ "node_modules/thenify-all": {
+ "version": "1.6.0",
+ "resolved": "https://registry.npmjs.org/thenify-all/-/thenify-all-1.6.0.tgz",
+ "integrity": "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "thenify": ">= 3.1.0 < 4"
+ },
+ "engines": {
+ "node": ">=0.8"
+ }
+ },
+ "node_modules/tinyexec": {
+ "version": "0.3.2",
+ "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
+ "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/tinyglobby": {
+ "version": "0.2.16",
+ "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+ "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "fdir": "^6.5.0",
+ "picomatch": "^4.0.4"
+ },
+ "engines": {
+ "node": ">=12.0.0"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/SuperchupuDev"
+ }
+ },
+ "node_modules/tree-kill": {
+ "version": "1.2.2",
+ "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz",
+ "integrity": "sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "tree-kill": "cli.js"
+ }
+ },
+ "node_modules/ts-interface-checker": {
+ "version": "0.1.13",
+ "resolved": "https://registry.npmjs.org/ts-interface-checker/-/ts-interface-checker-0.1.13.tgz",
+ "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==",
+ "dev": true,
+ "license": "Apache-2.0"
+ },
+ "node_modules/tsup": {
+ "version": "8.5.1",
+ "resolved": "https://registry.npmjs.org/tsup/-/tsup-8.5.1.tgz",
+ "integrity": "sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "bundle-require": "^5.1.0",
+ "cac": "^6.7.14",
+ "chokidar": "^4.0.3",
+ "consola": "^3.4.0",
+ "debug": "^4.4.0",
+ "esbuild": "^0.27.0",
+ "fix-dts-default-cjs-exports": "^1.0.0",
+ "joycon": "^3.1.1",
+ "picocolors": "^1.1.1",
+ "postcss-load-config": "^6.0.1",
+ "resolve-from": "^5.0.0",
+ "rollup": "^4.34.8",
+ "source-map": "^0.7.6",
+ "sucrase": "^3.35.0",
+ "tinyexec": "^0.3.2",
+ "tinyglobby": "^0.2.11",
+ "tree-kill": "^1.2.2"
+ },
+ "bin": {
+ "tsup": "dist/cli-default.js",
+ "tsup-node": "dist/cli-node.js"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "peerDependencies": {
+ "@microsoft/api-extractor": "^7.36.0",
+ "@swc/core": "^1",
+ "postcss": "^8.4.12",
+ "typescript": ">=4.5.0"
+ },
+ "peerDependenciesMeta": {
+ "@microsoft/api-extractor": {
+ "optional": true
+ },
+ "@swc/core": {
+ "optional": true
+ },
+ "postcss": {
+ "optional": true
+ },
+ "typescript": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/typescript": {
+ "version": "5.9.3",
+ "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+ "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "bin": {
+ "tsc": "bin/tsc",
+ "tsserver": "bin/tsserver"
+ },
+ "engines": {
+ "node": ">=14.17"
+ }
+ },
+ "node_modules/ufo": {
+ "version": "1.6.4",
+ "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.4.tgz",
+ "integrity": "sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/undici-types": {
+ "version": "6.21.0",
+ "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+ "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/unicorn-magic": {
+ "version": "0.3.0",
+ "resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.3.0.tgz",
+ "integrity": "sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ },
+ "node_modules/which": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+ "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+ "license": "ISC",
+ "dependencies": {
+ "isexe": "^2.0.0"
+ },
+ "bin": {
+ "node-which": "bin/node-which"
+ },
+ "engines": {
+ "node": ">= 8"
+ }
+ },
+ "node_modules/yoctocolors": {
+ "version": "2.1.2",
+ "resolved": "https://registry.npmjs.org/yoctocolors/-/yoctocolors-2.1.2.tgz",
+ "integrity": "sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/sindresorhus"
+ }
+ }
+ }
+}
diff --git a/tui/package.json b/tui/package.json
new file mode 100644
index 0000000..682e5f3
--- /dev/null
+++ b/tui/package.json
@@ -0,0 +1,42 @@
+{
+ "name": "brainapi",
+ "version": "0.1.0",
+ "description": "Interactive installer and runtime CLI for BrainAPI.",
+ "license": "MIT",
+ "type": "module",
+ "bin": {
+ "brainapi": "dist/index.js"
+ },
+ "files": [
+ "dist",
+ "README.md",
+ "LICENSE"
+ ],
+ "engines": {
+ "node": ">=18.17"
+ },
+ "scripts": {
+ "sync:install-extras": "node scripts/sync-install-extras.mjs",
+ "prebuild": "npm run sync:install-extras",
+ "build": "tsup",
+ "predev": "npm run sync:install-extras",
+ "dev": "tsup --watch",
+ "typecheck": "npm run sync:install-extras && tsc --noEmit",
+ "start": "node dist/index.js",
+ "prepublishOnly": "npm run build"
+ },
+ "dependencies": {
+ "@clack/prompts": "^0.7.0",
+ "execa": "^9.4.0",
+ "picocolors": "^1.1.0",
+ "simple-git": "^3.27.0"
+ },
+ "devDependencies": {
+ "@types/node": "^22.7.4",
+ "tsup": "^8.3.0",
+ "typescript": "^5.6.2"
+ },
+ "publishConfig": {
+ "access": "public"
+ }
+}
diff --git a/tui/scripts/sync-install-extras.mjs b/tui/scripts/sync-install-extras.mjs
new file mode 100644
index 0000000..48391fd
--- /dev/null
+++ b/tui/scripts/sync-install-extras.mjs
@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "..", "..");
+const sourcePath = resolve(repoRoot, "scripts", "install_extras.py");
+const targetPath = resolve(here, "..", "src", "embedded", "install-extras-script.ts");
+
+const script = readFileSync(sourcePath, "utf8");
+mkdirSync(dirname(targetPath), { recursive: true });
+const out = `// Auto-generated from scripts/install_extras.py — do not edit by hand.
+// Regenerate with: npm run sync:install-extras (also runs as prebuild).
+
+export const INSTALL_EXTRAS_SCRIPT = ${JSON.stringify(script)};
+`;
+writeFileSync(targetPath, out, "utf8");
+console.log(`Synced ${sourcePath} → ${targetPath} (${script.length} bytes)`);
diff --git a/tui/src/commands/config.ts b/tui/src/commands/config.ts
new file mode 100644
index 0000000..2cdb1dc
--- /dev/null
+++ b/tui/src/commands/config.ts
@@ -0,0 +1,304 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readState, updateState } from "../lib/state.js";
+import { askUseDefaults, DEFAULT_DBS } from "../flows/defaults.js";
+import { askDatabases } from "../flows/services.js";
+import { askModels } from "../flows/models.js";
+import {
+ askPipeline,
+ ocrToExtras,
+ postgresBackendExtras,
+} from "../flows/pipeline.js";
+import { askConnections } from "../flows/connections.js";
+import { askAuth } from "../flows/auth.js";
+import { askServicesRuntime } from "../flows/services-runtime.js";
+import {
+ runSetupWizard,
+ toInitChoices,
+ type SetupDraft,
+} from "../flows/setup-wizard.js";
+import { writeEnvFromChoices } from "../lib/write-env.js";
+import { installExtras, missingExtras } from "../lib/python.js";
+import { isPromptBack, pickOne } from "../lib/prompts.js";
+import type { InitChoices } from "../types.js";
+
+const MENU_BACK_HINT = "Return to configuration menu";
+
+type ConfigMenuSection =
+ | "defaults"
+ | "databases"
+ | "runtime"
+ | "models"
+ | "pipeline"
+ | "connections"
+ | "auth"
+ | "wizard"
+ | "save"
+ | "exit";
+
+interface ConfigDraft extends SetupDraft {}
+
+function draftSummary(draft: ConfigDraft): string {
+ const lines: string[] = [];
+ if (draft.dbs) {
+ lines.push(
+ `Databases: ${draft.dbs.vectorDb} / ${draft.dbs.dataDb} / ${draft.dbs.graphDb}`,
+ );
+ } else {
+ lines.push("Databases: not configured");
+ }
+ lines.push(
+ draft.servicesRuntime
+ ? `Services runtime: ${draft.servicesRuntime}`
+ : "Services runtime: not configured",
+ );
+ lines.push(draft.models ? "Models: configured" : "Models: not configured");
+ lines.push(
+ draft.pipeline
+ ? `Pipeline OCR: ${draft.pipeline.ocrMode}`
+ : "Pipeline OCR: not configured",
+ );
+ lines.push(
+ draft.connections ? "Connections: configured" : "Connections: not configured",
+ );
+ lines.push(
+ draft.auth?.brainpatToken ? "Auth token: set" : "Auth token: not configured",
+ );
+ return lines.join("\n");
+}
+
+function missingForSave(draft: ConfigDraft): string[] {
+ const missing: string[] = [];
+ if (!draft.dbs) missing.push("databases");
+ if (!draft.servicesRuntime) missing.push("services runtime");
+ if (!draft.models) missing.push("models");
+ if (!draft.pipeline) missing.push("pipeline");
+ if (!draft.connections) missing.push("connections");
+ if (!draft.auth?.brainpatToken) missing.push("authentication");
+ return missing;
+}
+
+async function configMainMenu(): Promise<ConfigMenuSection> {
+ return pickOne<ConfigMenuSection>({
+ message: "What would you like to configure?",
+ options: [
+ {
+ value: "defaults",
+ label: "Apply default stack",
+ hint: "NetworkX + Postgres + remote LLM",
+ },
+ { value: "databases", label: "Databases" },
+ { value: "runtime", label: "Services runtime" },
+ { value: "models", label: "Models (LLM & embeddings)" },
+ { value: "pipeline", label: "Pipeline (OCR)" },
+ { value: "connections", label: "Connection details" },
+ { value: "auth", label: "Authentication token" },
+ {
+ value: "wizard",
+ label: "Configure all (step-by-step)",
+ hint: "Full flow with back between steps",
+ },
+ { value: "save", label: "Save & apply changes" },
+ { value: "exit", label: "Exit without saving" },
+ ],
+ });
+}
+
+async function applyDefaultsSection(draft: ConfigDraft): Promise<void> {
+ const useDefaults = await askUseDefaults({
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ });
+ if (isPromptBack(useDefaults) || !useDefaults) {
+ return;
+ }
+ draft.usedDefaults = true;
+ draft.dbs = DEFAULT_DBS;
+ draft.pipeline = { ocrMode: "docparser" };
+ const models = await askModels({ prechosenMode: "remote" });
+ if (!isPromptBack(models)) {
+ draft.models = models;
+ }
+ p.log.success("Default stack applied to draft.");
+}
+
+async function configureDatabases(draft: ConfigDraft): Promise<void> {
+ const dbs = await askDatabases({
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ initial: draft.dbs,
+ });
+ if (isPromptBack(dbs)) {
+ return;
+ }
+ draft.dbs = dbs;
+ draft.usedDefaults = false;
+ p.log.success("Databases updated.");
+}
+
+async function configureRuntime(draft: ConfigDraft): Promise<void> {
+ if (!draft.dbs) {
+ p.log.warn("Configure databases first.");
+ return;
+ }
+ const runtime = await askServicesRuntime(draft.dbs, {
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ initialValue: draft.servicesRuntime,
+ });
+ if (isPromptBack(runtime)) {
+ return;
+ }
+ draft.servicesRuntime = runtime;
+ p.log.success("Services runtime updated.");
+}
+
+async function configureModels(draft: ConfigDraft): Promise<void> {
+ const models = await askModels({
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ initialMode: draft.models?.mode,
+ });
+ if (isPromptBack(models)) {
+ return;
+ }
+ draft.models = models;
+ p.log.success("Models updated.");
+}
+
+async function configurePipeline(draft: ConfigDraft): Promise<void> {
+ const pipeline = await askPipeline({
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ initialOcrMode: draft.pipeline?.ocrMode,
+ });
+ if (isPromptBack(pipeline)) {
+ return;
+ }
+ draft.pipeline = pipeline;
+ draft.usedDefaults = false;
+ p.log.success("Pipeline updated.");
+}
+
+async function configureConnections(draft: ConfigDraft): Promise<void> {
+ if (!draft.dbs) {
+ p.log.warn("Configure databases first.");
+ return;
+ }
+ const connections = await askConnections(draft.dbs);
+ draft.connections = connections;
+ p.log.success("Connections updated.");
+}
+
+async function configureAuth(draft: ConfigDraft): Promise<void> {
+ const auth = await askAuth({
+ allowBack: true,
+ backHint: MENU_BACK_HINT,
+ });
+ if (isPromptBack(auth)) {
+ return;
+ }
+ draft.auth = auth;
+ p.log.success("Authentication token updated.");
+}
+
+async function runConfigWizard(draft: ConfigDraft): Promise<void> {
+ const completed = await runSetupWizard(draft, {
+ firstStepBack: "return",
+ firstStepBackHint: MENU_BACK_HINT,
+ stepBackHint: "Previous step",
+ });
+ if (completed) {
+ p.log.success("Full configuration complete.");
+ }
+}
+
+async function saveDraft(draft: ConfigDraft): Promise<boolean> {
+ const missing = missingForSave(draft);
+ if (missing.length > 0) {
+ p.log.error(
+ "Cannot save yet. Still need: " + missing.join(", ") + ".",
+ );
+ p.note(draftSummary(draft), "Current draft");
+ return false;
+ }
+
+ const choices = toInitChoices(draft);
+ await writeEnvFromChoices(choices);
+ await updateState({ envWritten: true, servicesRuntime: choices.servicesRuntime });
+
+ const extras = [
+ ...ocrToExtras(choices.pipeline.ocrMode),
+ ...postgresBackendExtras(choices.dbs),
+ ];
+ const missingExtrasList = await missingExtras(extras);
+ if (missingExtrasList.length > 0) {
+ p.log.info(`Installing missing extras: ${missingExtrasList.join(", ")}`);
+ await installExtras(missingExtrasList);
+ p.log.success("Extras installed.");
+ }
+
+ p.outro(pc.green(".env rewritten."));
+ return true;
+}
+
+export async function runConfig(): Promise<void> {
+ p.intro(pc.bgCyan(pc.black(" brainapi ")) + " " + pc.dim("config"));
+
+ const state = await readState();
+ if (!state || !state.cloned) {
+ p.cancel(
+ "No brainapi install detected. Run " + pc.cyan("brainapi init") + " first.",
+ );
+ process.exit(1);
+ }
+
+ const draft: ConfigDraft = {
+ servicesRuntime: state.servicesRuntime ?? undefined,
+ };
+
+ p.note(
+ "Pick a section to update, or use step-by-step mode. Select Back on any prompt to go back.",
+ "Configuration",
+ );
+
+ while (true) {
+ p.note(draftSummary(draft), "Current draft");
+ const section = await configMainMenu();
+
+ switch (section) {
+ case "exit":
+ p.cancel("No changes saved.");
+ return;
+ case "save":
+ if (await saveDraft(draft)) {
+ return;
+ }
+ break;
+ case "defaults":
+ await applyDefaultsSection(draft);
+ break;
+ case "databases":
+ await configureDatabases(draft);
+ break;
+ case "runtime":
+ await configureRuntime(draft);
+ break;
+ case "models":
+ await configureModels(draft);
+ break;
+ case "pipeline":
+ await configurePipeline(draft);
+ break;
+ case "connections":
+ await configureConnections(draft);
+ break;
+ case "auth":
+ await configureAuth(draft);
+ break;
+ case "wizard":
+ await runConfigWizard(draft);
+ break;
+ }
+ }
+}
diff --git a/tui/src/commands/doctor.ts b/tui/src/commands/doctor.ts
new file mode 100644
index 0000000..118944a
--- /dev/null
+++ b/tui/src/commands/doctor.ts
@@ -0,0 +1,181 @@
+import { access } from "node:fs/promises";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { detectPython } from "../lib/python.js";
+import { detectDocker } from "../lib/docker.js";
+import { tcpProbe } from "../lib/net.js";
+import { isOllamaRunning } from "../lib/ollama.js";
+import { readEnvFile } from "../lib/env.js";
+import { envFilePath, venvPath } from "../lib/paths.js";
+import { readState } from "../lib/state.js";
+
+interface CheckResult {
+ name: string;
+ ok: boolean | "warn";
+ detail?: string;
+}
+
+function getValue(
+ env: Awaited<ReturnType<typeof readEnvFile>>,
+ key: string,
+): string | undefined {
+ const idx = env.keyIndex.get(key);
+ if (idx === undefined) return undefined;
+ const raw = (env.lines[idx] ?? "").split("=").slice(1).join("=");
+ return raw.trim().replace(/^"|"$/g, "");
+}
+
+async function fileExists(path: string): Promise<boolean> {
+ try {
+ await access(path);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function statusGlyph(ok: boolean | "warn"): string {
+ if (ok === true) return pc.green("OK");
+ if (ok === "warn") return pc.yellow("WARN");
+ return pc.red("FAIL");
+}
+
+export async function runDoctor(): Promise<void> {
+ p.intro(pc.bgCyan(pc.black(" brainapi ")) + " " + pc.dim("doctor"));
+
+ const results: CheckResult[] = [];
+
+ const py = await detectPython();
+ results.push({
+ name: "Python >= 3.11",
+ ok: py !== null,
+ detail: py ? `${py.bin} (${py.version.join(".")})` : "Not found on PATH",
+ });
+
+ results.push({
+ name: "Python venv",
+ ok: await fileExists(venvPath()),
+ detail: venvPath(),
+ });
+
+ const state = await readState();
+ results.push({
+ name: "Install state",
+ ok: state !== null,
+ detail: state ? "~/.brainapi/state.json present" : "missing",
+ });
+
+ let env: Awaited<ReturnType<typeof readEnvFile>> | null = null;
+ if (await fileExists(envFilePath())) {
+ env = await readEnvFile(envFilePath());
+ results.push({ name: ".env", ok: true, detail: envFilePath() });
+ } else {
+ results.push({ name: ".env", ok: false, detail: "missing — run brainapi init" });
+ }
+
+ const runtime = state?.servicesRuntime ?? "docker";
+ if (runtime === "docker") {
+ const dockerState = await detectDocker();
+ results.push({
+ name: "Docker",
+ ok: dockerState === "ok" ? true : dockerState === "daemon_down" ? "warn" : false,
+ detail:
+ dockerState === "ok"
+ ? "installed and daemon up"
+ : dockerState === "daemon_down"
+ ? "installed but daemon not running"
+ : "not installed",
+ });
+ } else {
+ results.push({
+ name: "Docker",
+ ok: "warn",
+ detail: "not required (services runtime = manual)",
+ });
+ }
+
+ if (env) {
+ const modelsMode = getValue(env, "MODELS_MODE");
+ if (modelsMode === "local") {
+ const host = getValue(env, "OLLAMA_HOST") ?? "localhost";
+ const port = Number(getValue(env, "OLLAMA_PORT") ?? "11434");
+ const ok = await isOllamaRunning({ host, port });
+ results.push({
+ name: "Ollama",
+ ok,
+ detail: `http://${host}:${port}`,
+ });
+ } else if (modelsMode === "remote") {
+ const credPath = getValue(env, "GCP_CREDENTIALS_PATH");
+ results.push({
+ name: "GCP credentials",
+ ok: credPath ? await fileExists(credPath) : false,
+ detail: credPath ?? "GCP_CREDENTIALS_PATH not set",
+ });
+ }
+
+ const services: Array<[string, string, string]> = [
+ ["Redis", getValue(env, "REDIS_HOST") ?? "localhost", getValue(env, "REDIS_PORT") ?? "6379"],
+ ];
+ if (
+ getValue(env, "VECTOR_DB") === "postgresql" ||
+ getValue(env, "DATA_DB") === "postgresql" ||
+ getValue(env, "GRAPH_DB") === "networkx"
+ ) {
+ services.push([
+ "PostgreSQL",
+ getValue(env, "POSTGRES_HOST") ?? "localhost",
+ getValue(env, "POSTGRES_PORT") ?? "5432",
+ ]);
+ }
+ if (getValue(env, "GRAPH_DB") === "neo4j") {
+ services.push([
+ "Neo4j",
+ getValue(env, "NEO4J_HOST") ?? "localhost",
+ getValue(env, "NEO4J_PORT") ?? "7687",
+ ]);
+ }
+ if (getValue(env, "VECTOR_DB") === "milvus") {
+ services.push([
+ "Milvus",
+ getValue(env, "MILVUS_HOST") ?? "localhost",
+ getValue(env, "MILVUS_PORT") ?? "19530",
+ ]);
+ }
+ if (getValue(env, "DATA_DB") === "mongo") {
+ services.push([
+ "Mongo",
+ getValue(env, "MONGO_HOST") ?? "localhost",
+ getValue(env, "MONGO_PORT") ?? "27017",
+ ]);
+ }
+ if (getValue(env, "CELERY_BACKEND") === "rabbitmq") {
+ services.push([
+ "RabbitMQ",
+ getValue(env, "RABBITMQ_HOST") ?? "localhost",
+ getValue(env, "RABBITMQ_PORT") ?? "5672",
+ ]);
+ }
+
+ for (const [name, host, portRaw] of services) {
+ const port = Number(portRaw);
+ const ok = await tcpProbe({ host, port });
+ results.push({
+ name,
+ ok,
+ detail: `${host}:${port}`,
+ });
+ }
+ }
+
+ const lines = results.map((r) => `${statusGlyph(r.ok)} ${r.name}${r.detail ? pc.dim(` — ${r.detail}`) : ""}`);
+ p.note(lines.join("\n"), "Diagnostics");
+
+ const fails = results.filter((r) => r.ok === false).length;
+ if (fails === 0) {
+ p.outro(pc.green("All checks passed."));
+ } else {
+ p.outro(pc.red(`${fails} check(s) failed.`));
+ process.exit(1);
+ }
+}
diff --git a/tui/src/commands/init.ts b/tui/src/commands/init.ts
new file mode 100644
index 0000000..e8430bb
--- /dev/null
+++ b/tui/src/commands/init.ts
@@ -0,0 +1,228 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { sourcePath } from "../lib/paths.js";
+import {
+ defaultState,
+ ensureStateDir,
+ readState,
+ updateState,
+ writeState,
+} from "../lib/state.js";
+import { ensureRepo, isClonedRepo } from "../lib/git.js";
+import { ensurePython } from "../lib/python-recovery.js";
+import {
+ createVenv,
+ installDeps,
+ venvExists,
+} from "../lib/python.js";
+import { runSetupWizard, toInitChoices, type SetupDraft } from "../flows/setup-wizard.js";
+import {
+ ocrToExtras,
+ postgresBackendExtras,
+} from "../flows/pipeline.js";
+import { writeEnvFromChoices } from "../lib/write-env.js";
+import { ensureDocker } from "../lib/docker-recovery.js";
+import { bringUpServices, bringUpServicesManually } from "../lib/bring-up.js";
+import { targetFromConnections } from "../lib/service-target.js";
+import { askConfirm } from "../lib/prompts.js";
+import type {
+ Connections,
+ DbChoices,
+ InitChoices,
+ ServicesRuntime,
+} from "../types.js";
+import { type ServiceName } from "../constants.js";
+
+export interface InitOptions {
+ repoUrl?: string;
+ branch?: string;
+ force?: boolean;
+}
+
+function intro(): void {
+ p.intro(pc.bgCyan(pc.black(" brainapi ")) + " " + pc.dim("init"));
+}
+
+function outro(): void {
+ p.outro(
+ `${pc.green("Setup complete.")} Try ${pc.cyan("brainapi start")} when you're ready.`,
+ );
+}
+
+function pickedServices(dbs: DbChoices): ServiceName[] {
+ const set = new Set<ServiceName>(["redis"]);
+ if (
+ dbs.vectorDb === "postgresql" ||
+ dbs.dataDb === "postgresql" ||
+ dbs.graphDb === "networkx"
+ ) {
+ set.add("postgresql");
+ }
+ if (dbs.graphDb === "neo4j") set.add("neo4j");
+ if (dbs.vectorDb === "milvus") set.add("milvus");
+ if (dbs.dataDb === "mongo") set.add("mongo");
+ return [...set];
+}
+
+
+async function clonePhase(opts: InitOptions): Promise<void> {
+ if (await isClonedRepo()) {
+ p.log.info("Repository already cloned — pulling latest");
+ }
+ const spinner = p.spinner();
+ spinner.start("Cloning brainapi source");
+ try {
+ const state = await readState();
+ const repoUrl = opts.repoUrl ?? state?.repoUrl ?? defaultState().repoUrl;
+ const branch = opts.branch ?? state?.branch ?? defaultState().branch;
+ const result = await ensureRepo({ repoUrl, branch });
+ spinner.stop(
+ result === "cloned"
+ ? `Cloned to ${pc.cyan(sourcePath())}`
+ : `Updated ${pc.cyan(sourcePath())}`,
+ );
+ } catch (err) {
+ spinner.stop(pc.red("Clone failed."));
+ throw err;
+ }
+}
+
+async function ensureVenv(pythonBin: string): Promise<void> {
+ const spinner = p.spinner();
+ if (await venvExists()) {
+ p.log.info("Virtualenv already exists — skipping creation");
+ return;
+ }
+ spinner.start("Creating Python venv (.venv)");
+ try {
+ await createVenv(pythonBin);
+ spinner.stop("Virtualenv created");
+ } catch (err) {
+ spinner.stop(pc.red("Failed to create venv"));
+ throw err;
+ }
+}
+
+async function installPhase(extras: string[]): Promise<void> {
+ if (extras.length === 0) {
+ p.log.info("Installing Python base dependencies");
+ } else {
+ p.log.info(
+ `Installing Python base dependencies + extras (${extras.join(", ")})`,
+ );
+ }
+ await installDeps({ extras });
+ p.log.success("Dependencies installed");
+}
+
+async function configurePhase(): Promise<InitChoices> {
+ const draft: SetupDraft = {};
+ await runSetupWizard(draft, {
+ firstStepBack: "cancel",
+ firstStepBackHint: "Cancel setup",
+ stepBackHint: "Previous step",
+ });
+ return toInitChoices(draft);
+}
+
+async function servicesPhase(
+ dbs: DbChoices,
+ connections: Connections,
+ runtime: ServicesRuntime,
+): Promise<void> {
+ const services = pickedServices(dbs);
+ const items = services.map((service) => ({
+ service,
+ target: targetFromConnections(service, connections),
+ }));
+
+ if (runtime === "manual") {
+ p.log.step("Checking backing services (manual runtime)");
+ await bringUpServicesManually(items);
+ await updateState({
+ containersStarted: false,
+ selectedServices: services,
+ servicesRuntime: "manual",
+ });
+ return;
+ }
+
+ const startNow = await askConfirm({
+ message: "Start docker compose containers now for the services you picked?",
+ initialValue: true,
+ });
+ if (!startNow) {
+ p.log.info(
+ "Skipping. Start them later with " +
+ pc.cyan("brainapi start") +
+ " or " +
+ pc.cyan("docker compose -f src/lib/<service>/docker-compose.yaml up -d"),
+ );
+ await updateState({
+ selectedServices: services,
+ servicesRuntime: "docker",
+ });
+ return;
+ }
+
+ const ready = await ensureDocker();
+ if (ready === "cancelled") {
+ p.log.warn(
+ "Docker is not available — setup is otherwise complete. Re-run " +
+ pc.cyan("brainapi start") +
+ " once Docker is up.",
+ );
+ return;
+ }
+
+ await bringUpServices(items);
+ await updateState({
+ containersStarted: true,
+ selectedServices: services,
+ servicesRuntime: "docker",
+ });
+}
+
+export async function runInit(opts: InitOptions = {}): Promise<void> {
+ intro();
+ await ensureStateDir();
+ const existing = await readState();
+ if (existing && !opts.force) {
+ p.log.info(
+ "Resuming from previous install state at " + pc.cyan("~/.brainapi/state.json"),
+ );
+ } else if (!existing) {
+ await writeState(defaultState());
+ }
+
+ let python = await ensurePython();
+ await clonePhase(opts);
+
+ const recheck = await ensurePython();
+ if (recheck.bin !== python.bin) {
+ p.log.info(`Using ${recheck.bin} (${recheck.version.join(".")})`);
+ }
+ python = recheck;
+
+ await ensureVenv(python.bin);
+
+ const choices = await configurePhase();
+ const extras = [
+ ...ocrToExtras(choices.pipeline.ocrMode),
+ ...postgresBackendExtras(choices.dbs),
+ ];
+
+ await installPhase(extras);
+
+ await writeEnvFromChoices(choices);
+ await updateState({ envWritten: true });
+ p.log.success(".env written");
+
+ await servicesPhase(
+ choices.dbs,
+ choices.connections,
+ choices.servicesRuntime,
+ );
+
+ outro();
+}
diff --git a/tui/src/commands/start.ts b/tui/src/commands/start.ts
new file mode 100644
index 0000000..8be2c3d
--- /dev/null
+++ b/tui/src/commands/start.ts
@@ -0,0 +1,216 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readState } from "../lib/state.js";
+import { ensureDocker } from "../lib/docker-recovery.js";
+import { bringUpServices, bringUpServicesManually } from "../lib/bring-up.js";
+import { targetFromEnv } from "../lib/service-target.js";
+import { envFileToProcessEnv, readEnvFile, setPipelineMode } from "../lib/env.js";
+import { syncDevSourceIfAvailable } from "../lib/sync-source.js";
+import { envFilePath, sourcePath, venvBin } from "../lib/paths.js";
+import {
+ installDeps,
+ missingRequiredPythonDeps,
+} from "../lib/python.js";
+import { runParallel } from "../lib/parallel.js";
+import {
+ API_DEFAULT_PORT,
+ MCP_DEFAULT_PORT,
+ SERVICE_COMPOSE_FILES,
+ type ServiceName,
+} from "../constants.js";
+import type { PipelineMode, ServicesRuntime } from "../types.js";
+
+function getEnv(
+ env: Awaited<ReturnType<typeof readEnvFile>>,
+ key: string,
+): string | undefined {
+ const idx = env.keyIndex.get(key);
+ if (idx === undefined) return undefined;
+ const raw = (env.lines[idx] ?? "").split("=").slice(1).join("=");
+ return raw.trim().replace(/^"|"$/g, "");
+}
+
+function pickedFromEnv(env: Awaited<ReturnType<typeof readEnvFile>>): ServiceName[] {
+ const services = new Set<ServiceName>(["redis"]);
+ const vector = getEnv(env, "VECTOR_DB");
+ const data = getEnv(env, "DATA_DB");
+ const graph = getEnv(env, "GRAPH_DB");
+ if (vector === "postgresql" || data === "postgresql" || graph === "networkx") {
+ services.add("postgresql");
+ }
+ if (graph === "neo4j") services.add("neo4j");
+ if (vector === "milvus") services.add("milvus");
+ if (data === "mongo") services.add("mongo");
+ if (getEnv(env, "CELERY_BACKEND") === "rabbitmq") services.add("rabbitmq");
+ return [...services].filter((s) => s in SERVICE_COMPOSE_FILES);
+}
+
+export interface StartOptions {
+ api?: boolean;
+ mcp?: boolean;
+ worker?: boolean;
+ services?: boolean;
+ pipelineMode?: PipelineMode;
+}
+
+export async function runStart(opts: StartOptions = {}): Promise<void> {
+ const wantApi = opts.api !== false;
+ const wantMcp = opts.mcp !== false;
+ const wantWorker = opts.worker !== false;
+ const wantServices = opts.services !== false;
+
+ p.intro(pc.bgCyan(pc.black(" brainapi ")) + " " + pc.dim("start"));
+
+ await syncDevSourceIfAvailable();
+
+ const state = await readState();
+ if (!state || !state.envWritten) {
+ p.cancel(
+ "No brainapi install detected. Run " + pc.cyan("brainapi init") + " first.",
+ );
+ process.exit(1);
+ }
+
+ if (opts.pipelineMode) {
+ await setPipelineMode(opts.pipelineMode);
+ p.log.info(`PIPELINE_MODE set to ${pc.cyan(opts.pipelineMode)}`);
+ }
+
+ const env = await readEnvFile(envFilePath());
+
+ if (await missingRequiredPythonDeps()) {
+ p.log.info("Installing missing Python dependencies for current .env...");
+ try {
+ await installDeps({ skipBase: true });
+ p.log.success("Python dependencies installed.");
+ } catch (err) {
+ p.log.error(
+ `Failed to install Python dependencies: ${
+ err instanceof Error ? err.message : String(err)
+ }`,
+ );
+ }
+ }
+
+ if (wantServices) {
+ const services = pickedFromEnv(env);
+ const runtime: ServicesRuntime = state.servicesRuntime ?? "docker";
+ const getter = (key: string) => getEnv(env, key);
+ const items = services.map((service) => ({
+ service,
+ target: targetFromEnv(service, getter),
+ }));
+
+ if (runtime === "manual") {
+ p.log.step("Checking backing services (manual runtime)");
+ await bringUpServicesManually(items);
+ } else {
+ const ready = await ensureDocker();
+ if (ready === "cancelled") {
+ p.cancel("Docker is not available. Aborting start.");
+ process.exit(1);
+ }
+ await bringUpServices(items);
+ }
+ } else {
+ p.log.info("Skipping backing services (--no-services).");
+ }
+
+ if (!wantApi && !wantMcp && !wantWorker) {
+ p.outro(pc.green("Services up. Skipping API/MCP/worker."));
+ return;
+ }
+
+ const processEnv = envFileToProcessEnv(env);
+ const jobs = buildJobs({ wantApi, wantMcp, wantWorker, processEnv });
+
+ p.note(
+ jobs
+ .map((j) => `${pc.bold(j.name.padEnd(7))} ${pc.dim(`${j.bin} ${j.args.join(" ")}`)}`)
+ .join("\n"),
+ "Starting (Ctrl-C to stop everything)",
+ );
+
+ const results = await runParallel(jobs);
+ const failed = results.filter((r) => r.code !== 0 && r.signal === null);
+ if (failed.length > 0) {
+ p.outro(
+ pc.red(
+ `Exited: ${failed.map((f) => `${f.name}=${f.code}`).join(", ")}`,
+ ),
+ );
+ process.exit(1);
+ }
+ p.outro(pc.green("All processes exited cleanly."));
+}
+
+function buildJobs(opts: {
+ wantApi: boolean;
+ wantMcp: boolean;
+ wantWorker: boolean;
+ processEnv: NodeJS.ProcessEnv;
+}): Array<{
+ name: string;
+ bin: string;
+ args: string[];
+ cwd: string;
+ env: NodeJS.ProcessEnv;
+}> {
+ const jobs: Array<{
+ name: string;
+ bin: string;
+ args: string[];
+ cwd: string;
+ env: NodeJS.ProcessEnv;
+ }> = [];
+ const cwd = sourcePath();
+
+ if (opts.wantApi) {
+ jobs.push({
+ name: "api",
+ bin: venvBin("uvicorn"),
+ args: [
+ "src.services.api.app:app",
+ "--host",
+ "0.0.0.0",
+ "--port",
+ String(API_DEFAULT_PORT),
+ "--reload",
+ ],
+ cwd,
+ env: opts.processEnv,
+ });
+ }
+ if (opts.wantMcp) {
+ jobs.push({
+ name: "mcp",
+ bin: venvBin("uvicorn"),
+ args: [
+ "src.services.mcp.app:app",
+ "--host",
+ "0.0.0.0",
+ "--port",
+ String(MCP_DEFAULT_PORT),
+ "--reload",
+ ],
+ cwd,
+ env: opts.processEnv,
+ });
+ }
+ if (opts.wantWorker) {
+ jobs.push({
+ name: "worker",
+ bin: venvBin("celery"),
+ args: [
+ "-A",
+ "src.workers.app",
+ "worker",
+ "--loglevel=info",
+ "--pool=threads",
+ ],
+ cwd,
+ env: opts.processEnv,
+ });
+ }
+ return jobs;
+}
diff --git a/tui/src/commands/update.ts b/tui/src/commands/update.ts
new file mode 100644
index 0000000..081ecae
--- /dev/null
+++ b/tui/src/commands/update.ts
@@ -0,0 +1,74 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { envFilePath, sourcePath } from "../lib/paths.js";
+import { readState } from "../lib/state.js";
+import { pullRepo } from "../lib/git.js";
+import { installDeps } from "../lib/python.js";
+import { readEnvFile } from "../lib/env.js";
+import { syncDevSourceIfAvailable } from "../lib/sync-source.js";
+
+function getEnv(
+ env: Awaited<ReturnType<typeof readEnvFile>>,
+ key: string,
+): string | undefined {
+ const idx = env.keyIndex.get(key);
+ if (idx === undefined) return undefined;
+ const raw = (env.lines[idx] ?? "").split("=").slice(1).join("=");
+ return raw.trim().replace(/^"|"$/g, "");
+}
+
+async function extrasFromEnv(): Promise<string[]> {
+ try {
+ const env = await readEnvFile(envFilePath());
+ const ocr = getEnv(env, "OCR_MODE");
+ const extras = ocr === "docling" ? ["docling-ocr"] : [];
+ const vector = getEnv(env, "VECTOR_DB");
+ const data = getEnv(env, "DATA_DB");
+ const graph = getEnv(env, "GRAPH_DB");
+ if (
+ vector === "postgresql" ||
+ data === "postgresql" ||
+ graph === "networkx"
+ ) {
+ extras.push("postgresql-backend");
+ }
+ return extras;
+ } catch {
+ return [];
+ }
+}
+
+export async function runUpdate(): Promise<void> {
+ p.intro(pc.bgCyan(pc.black(" brainapi ")) + " " + pc.dim("update"));
+
+ const state = await readState();
+ if (!state || !state.cloned) {
+ p.cancel(
+ "No brainapi install detected. Run " + pc.cyan("brainapi init") + " first.",
+ );
+ process.exit(1);
+ }
+
+ const branch = state.branch || "main";
+ const spinner = p.spinner();
+ spinner.start(`git pull origin ${branch} in ${sourcePath()}`);
+ try {
+ await pullRepo(branch);
+ spinner.stop("Repository updated");
+ } catch (err) {
+ spinner.stop(pc.red("git pull failed"));
+ throw err;
+ }
+
+ await syncDevSourceIfAvailable();
+
+ const extras = await extrasFromEnv();
+ if (extras.length === 0) {
+ p.log.step("Reinstalling Python base dependencies");
+ } else {
+ p.log.step(`Reinstalling Python base + extras (${extras.join(", ")})`);
+ }
+ await installDeps({ extras });
+
+ p.outro(pc.green("brainapi is up to date."));
+}
diff --git a/tui/src/constants.ts b/tui/src/constants.ts
new file mode 100644
index 0000000..4d4b141
--- /dev/null
+++ b/tui/src/constants.ts
@@ -0,0 +1,242 @@
+export const DEFAULT_REPO_URL = "https://github.com/Lumen-Labs/brainapi2.git";
+export const DEFAULT_BRANCH = "main";
+export const MIN_PYTHON_VERSION: [number, number] = [3, 11];
+export const PYTHON_CANDIDATES = [
+ "python3.13",
+ "python3.12",
+ "python3.11",
+ "python3",
+ "python",
+];
+
+export const OLLAMA_DEFAULT_HOST = "localhost";
+export const OLLAMA_DEFAULT_PORT = 11434;
+export const OLLAMA_DEFAULT_SMALL_MODEL = "hf.co/unsloth/Qwen3-14B-GGUF:Q4_K_M";
+export const OLLAMA_DEFAULT_LARGE_MODEL = "hf.co/unsloth/Qwen3-14B-GGUF:Q4_K_M";
+
+export const GCP_DEFAULT_SMALL_MODEL = "gemini-3-flash-preview";
+export const GCP_DEFAULT_LARGE_MODEL = "gemini-3-flash-preview";
+export const GCP_DEFAULT_EMBEDDING_MODEL = "text-embedding-005";
+
+export const AZURE_DEFAULT_LARGE_MODEL = "gpt-4o";
+export const AZURE_DEFAULT_SMALL_MODEL = "gpt-4o-mini";
+export const AZURE_DEFAULT_LARGE_API_VERSION = "2024-12-01-preview";
+export const AZURE_DEFAULT_EMBEDDING_MODEL = "text-embedding-3-large";
+
+export const OPENAI_DEFAULT_SMALL_MODEL = "gpt-4o-mini";
+export const OPENAI_DEFAULT_LARGE_MODEL = "gpt-4o";
+export const OPENAI_DEFAULT_EMBEDDING_MODEL = "text-embedding-3-large";
+
+export const KNOWN_EMBEDDING_MODEL_DIMENSIONS: Record<string, number> = {
+ "nomic-embed-text": 768,
+ "mxbai-embed-large": 1024,
+ "all-minilm": 384,
+ "text-embedding-3-large": 3072,
+ "text-embedding-3-small": 1536,
+ "text-embedding-ada-002": 1536,
+ "text-embedding-005": 768,
+ "text-embedding-004": 768,
+ "amazon.titan-embed-text-v2:0": 1024,
+ "amazon.titan-embed-text-v1": 1536,
+ "intfloat/e5-small": 384,
+ "paraphrase-multilingual-minilm-l12-v2": 384,
+};
+
+export function lookupEmbeddingDimensions(model: string): number | undefined {
+ const normalized = model.trim().toLowerCase();
+ if (normalized in KNOWN_EMBEDDING_MODEL_DIMENSIONS) {
+ return KNOWN_EMBEDDING_MODEL_DIMENSIONS[normalized];
+ }
+ const entries = Object.entries(KNOWN_EMBEDDING_MODEL_DIMENSIONS).sort(
+ (a, b) => b[0].length - a[0].length,
+ );
+ for (const [key, dimensions] of entries) {
+ if (normalized.includes(key.toLowerCase())) {
+ return dimensions;
+ }
+ }
+ return undefined;
+}
+
+export const OPENAI_EMBEDDING_DIMENSIONS = {
+ nodesDimension: 3072,
+ tripletsDimension: 3072,
+ observationsDimension: 3072,
+ dataDimension: 3072,
+ relationshipsDimension: 3072,
+} as const;
+
+export const OPENAI_EMBEDDING_SMALL_DIMENSIONS = {
+ nodesDimension: 1536,
+ tripletsDimension: 1536,
+ observationsDimension: 1536,
+ dataDimension: 1536,
+ relationshipsDimension: 1536,
+} as const;
+
+export const BEDROCK_DEFAULT_REGION = "us-east-1";
+export const BEDROCK_DEFAULT_SMALL_MODEL = "us.anthropic.claude-3-5-haiku-20241022-v1:0";
+export const BEDROCK_DEFAULT_LARGE_MODEL = "us.anthropic.claude-3-7-sonnet-20250219-v1:0";
+export const BEDROCK_DEFAULT_EMBEDDING_MODEL = "amazon.titan-embed-text-v2:0";
+
+export const EMBEDDINGS_DEFAULTS = {
+ smallModel: "paraphrase-multilingual-MiniLM-L12-v2",
+ localModel: "nomic-embed-text:latest",
+ nodesDimension: 3072,
+ tripletsDimension: 3072,
+ observationsDimension: 3072,
+ dataDimension: 3072,
+ relationshipsDimension: 3072,
+} as const;
+
+export const OLLAMA_EMBEDDING_DIMENSIONS = {
+ nodesDimension: 768,
+ tripletsDimension: 768,
+ observationsDimension: 768,
+ dataDimension: 768,
+ relationshipsDimension: 768,
+} as const;
+
+export const SERVICE_DEFAULTS = {
+ redis: { host: "localhost", port: 6379 },
+ postgresql: {
+ host: "localhost",
+ port: 5432,
+ username: "postgres",
+ password: "password",
+ systemDatabase: "brainapi",
+ maintenanceDatabase: "postgres",
+ },
+ neo4j: {
+ host: "localhost",
+ port: 7687,
+ username: "neo4j",
+ password: "your_password",
+ },
+ milvus: {
+ host: "localhost",
+ port: 19530,
+ },
+ mongo: {
+ host: "localhost",
+ port: 27017,
+ username: "root",
+ password: "password",
+ },
+ rabbitmq: {
+ host: "localhost",
+ port: 5672,
+ username: "kalo",
+ password: "kalo",
+ },
+} as const;
+
+export const ENV_KEYS = {
+ graphDb: "GRAPH_DB",
+ dataDb: "DATA_DB",
+ vectorDb: "VECTOR_DB",
+ modelsMode: "MODELS_MODE",
+ brainpatToken: "BRAINPAT_TOKEN",
+ pipelineMode: "PIPELINE_MODE",
+ ocrMode: "OCR_MODE",
+ agenticArchitecture: "AGENTIC_ARCHITECTURE",
+ runGraphConsolidator: "RUN_GRAPH_CONSOLIDATOR",
+
+ redisHost: "REDIS_HOST",
+ redisPort: "REDIS_PORT",
+ celeryBackend: "CELERY_BACKEND",
+ celeryWorkerConcurrency: "CELERY_WORKER_CONCURRENCY",
+ celeryUnblockedWindowSeconds: "CELERY_UNBLOCKED_WINDOW_SECONDS",
+ celeryUnblockedMaxRetries: "CELERY_UNBLOCKED_MAX_RETRIES",
+ celeryQueueHealthThreshold: "CELERY_QUEUE_HEALTH_THRESHOLD",
+
+ postgresHost: "POSTGRES_HOST",
+ postgresPort: "POSTGRES_PORT",
+ postgresUsername: "POSTGRES_USERNAME",
+ postgresPassword: "POSTGRES_PASSWORD",
+ postgresSystemDatabase: "POSTGRES_SYSTEM_DATABASE",
+ postgresMaintenanceDatabase: "POSTGRES_MAINTENANCE_DATABASE",
+
+ neo4jHost: "NEO4J_HOST",
+ neo4jPort: "NEO4J_PORT",
+ neo4jUsername: "NEO4J_USERNAME",
+ neo4jPassword: "NEO4J_PASSWORD",
+
+ milvusHost: "MILVUS_HOST",
+ milvusPort: "MILVUS_PORT",
+ milvusUri: "MILVUS_URI",
+ milvusToken: "MILVUS_TOKEN",
+
+ mongoHost: "MONGO_HOST",
+ mongoPort: "MONGO_PORT",
+ mongoUsername: "MONGO_USERNAME",
+ mongoPassword: "MONGO_PASSWORD",
+ mongoConnectionString: "MONGO_CONNECTION_STRING",
+ mongoSystemDatabase: "MONGO_SYSTEM_DATABASE",
+
+ ollamaHost: "OLLAMA_HOST",
+ ollamaPort: "OLLAMA_PORT",
+ ollamaSmallModel: "OLLAMA_LLM_SMALL_MODEL",
+ ollamaLargeModel: "OLLAMA_LLM_LARGE_MODEL",
+
+ gcpProjectId: "GCP_PROJECT_ID",
+ gcpCredentialsPath: "GCP_CREDENTIALS_PATH",
+ llmSmallProvider: "LLM_SMALL_PROVIDER",
+ llmLargeProvider: "LLM_LARGE_PROVIDER",
+ embeddingsProvider: "EMBEDDINGS_PROVIDER",
+ gcpExtraSmallLlmModel: "GCP_EXTRA_SMALL_LLM_MODEL",
+ gcpSmallLlmModel: "GCP_SMALL_LLM_MODEL",
+ gcpLargeLlmModel: "GCP_LARGE_LLM_MODEL",
+ gcpEmbeddingModel: "GCP_EMBEDDING_MODEL",
+
+ azureSmallLlmModel: "AZURE_SMALL_LLM_MODEL",
+ azureLargeLlmModel: "AZURE_LARGE_LLM_MODEL",
+ azureLlmApiVersion: "AZURE_LLM_API_VERSION",
+ azureLlmEndpoint: "AZURE_LLM_ENDPOINT",
+ azureLlmSubscriptionKey: "AZURE_LLM_SUBSCRIPTION_KEY",
+ azureLargeLlmApiVersion: "AZURE_LARGE_LLM_API_VERSION",
+ azureLargeLlmEndpoint: "AZURE_LARGE_LLM_ENDPOINT",
+ azureLargeLlmSubscriptionKey: "AZURE_LARGE_LLM_SUBSCRIPTION_KEY",
+ azureEmbeddingModel: "AZURE_EMBEDDING_MODEL",
+ azureEmbeddingFullEndpoint: "AZURE_EMBEDDING_FULL_ENDPOINT",
+ azureEmbeddingKey: "AZURE_EMBEDDING_KEY",
+
+ openaiApiKey: "OPENAI_API_KEY",
+ openaiBaseUrl: "OPENAI_BASE_URL",
+ openaiSmallLlmModel: "OPENAI_SMALL_LLM_MODEL",
+ openaiLargeLlmModel: "OPENAI_LARGE_LLM_MODEL",
+ openaiEmbeddingModel: "OPENAI_EMBEDDING_MODEL",
+
+ bedrockRegion: "BEDROCK_REGION",
+ bedrockAccessKeyId: "BEDROCK_ACCESS_KEY_ID",
+ bedrockSecretAccessKey: "BEDROCK_SECRET_ACCESS_KEY",
+ bedrockSessionToken: "BEDROCK_SESSION_TOKEN",
+ bedrockSmallLlmModel: "BEDROCK_SMALL_LLM_MODEL",
+ bedrockLargeLlmModel: "BEDROCK_LARGE_LLM_MODEL",
+ bedrockEmbeddingModel: "BEDROCK_EMBEDDING_MODEL",
+
+ embeddingsFullEndpoint: "EMBEDDINGS_FULL_ENDPOINT",
+ embeddingsKey: "EMBEDDINGS_KEY",
+
+ embeddingsSmallModel: "EMBEDDINGS_SMALL_MODEL",
+ embeddingsLocalModel: "EMBEDDINGS_LOCAL_MODEL",
+ embeddingNodesDimension: "EMBEDDING_NODES_DIMENSION",
+ embeddingTripletsDimension: "EMBEDDING_TRIPLETS_DIMENSION",
+ embeddingObservationsDimension: "EMBEDDING_OBSERVATIONS_DIMENSION",
+ embeddingDataDimension: "EMBEDDING_DATA_DIMENSION",
+ embeddingRelationshipsDimension: "EMBEDDING_RELATIONSHIPS_DIMENSION",
+} as const;
+
+export const SERVICE_COMPOSE_FILES = {
+ redis: "src/lib/redis/docker-compose.yaml",
+ postgresql: "src/lib/postgresql/docker-compose.yaml",
+ neo4j: "src/lib/neo4j/docker-compose.yaml",
+ milvus: "src/lib/milvus/docker-compose.yaml",
+ mongo: "src/lib/mongo/docker-compose.yaml",
+ rabbitmq: "src/lib/rabbitmq/docker-compose.yaml",
+} as const;
+
+export type ServiceName = keyof typeof SERVICE_COMPOSE_FILES;
+
+export const API_DEFAULT_PORT = 8000;
+export const MCP_DEFAULT_PORT = 8001;
diff --git a/tui/src/embedded/install-extras-script.ts b/tui/src/embedded/install-extras-script.ts
new file mode 100644
index 0000000..a2a8fed
--- /dev/null
+++ b/tui/src/embedded/install-extras-script.ts
@@ -0,0 +1,4 @@
+// Auto-generated from scripts/install_extras.py — do not edit by hand.
+// Regenerate with: npm run sync:install-extras (also runs as prebuild).
+
+export const INSTALL_EXTRAS_SCRIPT = "\"\"\"\nInstall only the pyproject.toml optional-dependency groups that the active\n.env requires.\n\nUsage (no TUI required):\n\n python scripts/install_extras.py # auto-detect from .env\n python scripts/install_extras.py docling-ocr # force a specific group\n python scripts/install_extras.py --all # install every optional group\n python scripts/install_extras.py --dry-run # print pip command, don't run\n python scripts/install_extras.py --check # exit non-zero if missing\n\nReads ./.env (or $BRAINAPI_DOTENV) for OCR_MODE and any future toggles, then\ncalls `python -m pip install` against the active interpreter with the matching\nspecs from pyproject.toml's [project.optional-dependencies].\n\nSafe to re-run: pip is a no-op when the specs are already satisfied.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport importlib.util\nimport os\nimport re\nimport subprocess\nimport sys\nfrom pathlib import Path\n\ntry:\n import tomllib\nexcept ModuleNotFoundError:\n import tomli as tomllib # type: ignore[no-redef]\n\n\nREPO_ROOT = Path(__file__).resolve().parent.parent\nPYPROJECT_PATH = REPO_ROOT / \"pyproject.toml\"\nDEFAULT_ENV_PATH = Path(os.environ.get(\"BRAINAPI_DOTENV\", REPO_ROOT / \".env\"))\n\n\ndef parse_dotenv(path: Path) -> dict[str, str]:\n if not path.exists():\n return {}\n result: dict[str, str] = {}\n for raw in path.read_text(encoding=\"utf-8\").splitlines():\n line = raw.strip()\n if not line or line.startswith(\"#\") or \"=\" not in line:\n continue\n key, _, value = line.partition(\"=\")\n result[key.strip()] = value.strip().strip('\"').strip(\"'\")\n return result\n\n\ndef _load_pyproject() -> dict:\n if not PYPROJECT_PATH.exists():\n return {}\n with PYPROJECT_PATH.open(\"rb\") as fh:\n return tomllib.load(fh)\n\n\ndef _poetry_dep_to_spec(name: str, value) -> str | None:\n if name == \"python\":\n return None\n if isinstance(value, str):\n return name if value == \"*\" else f\"{name}{value}\"\n if isinstance(value, dict):\n version = value.get(\"version\", \"\")\n extras = value.get(\"extras\", []) or []\n head = name + (f\"[{','.join(extras)}]\" if extras else \"\")\n if not version or version == \"*\":\n return head\n return f\"{head}{version}\"\n return None\n\n\ndef load_base_deps() -> list[str]:\n data = _load_pyproject()\n project_deps = data.get(\"project\", {}).get(\"dependencies\", []) or []\n if project_deps:\n return list(project_deps)\n poetry_deps = (\n data.get(\"tool\", {}).get(\"poetry\", {}).get(\"dependencies\", {}) or {}\n )\n out: list[str] = []\n for name, value in poetry_deps.items():\n spec = _poetry_dep_to_spec(name, value)\n if spec:\n out.append(spec)\n return out\n\n\ndef load_optional_groups() -> dict[str, list[str]]:\n data = _load_pyproject()\n project_optional = (\n data.get(\"project\", {}).get(\"optional-dependencies\", {}) or {}\n )\n if project_optional:\n return {k: list(v) for k, v in project_optional.items()}\n poetry_groups = data.get(\"tool\", {}).get(\"poetry\", {}).get(\"group\", {}) or {}\n out: dict[str, list[str]] = {}\n for group_name, group_value in poetry_groups.items():\n if not isinstance(group_value, dict):\n continue\n deps = group_value.get(\"dependencies\", {}) or {}\n specs: list[str] = []\n for name, value in deps.items():\n spec = _poetry_dep_to_spec(name, value)\n if spec:\n specs.append(spec)\n if specs:\n out[group_name] = specs\n return out\n\n\nPOSTGRESQL_BACKEND_SPECS = [\n \"psycopg2-binary>=2.9.6,<3.0.0\",\n \"pgvector>=0.3.0,<1.0.0\",\n \"networkx>=3.0,<4.0.0\",\n]\n\n\ndef uses_postgresql_backend(env: dict[str, str]) -> bool:\n vector = env.get(\"VECTOR_DB\", \"milvus\").lower()\n data = env.get(\"DATA_DB\", \"mongo\").lower()\n graph = env.get(\"GRAPH_DB\", \"neo4j\").lower()\n return vector == \"postgresql\" or data == \"postgresql\" or graph == \"networkx\"\n\n\ndef required_groups(env: dict[str, str]) -> list[str]:\n groups: list[str] = []\n if env.get(\"OCR_MODE\", \"docparser\").lower() == \"docling\":\n groups.append(\"docling-ocr\")\n if uses_postgresql_backend(env):\n groups.append(\"postgresql-backend\")\n return groups\n\n\ndef required_backend_specs(env: dict[str, str]) -> list[str]:\n if not uses_postgresql_backend(env):\n return []\n optional = load_optional_groups()\n if \"postgresql-backend\" in optional:\n return []\n return list(POSTGRESQL_BACKEND_SPECS)\n\n\ndef package_name_from_spec(spec: str) -> str:\n spec = spec.strip()\n match = re.match(r\"^([A-Za-z0-9][A-Za-z0-9._-]*)\", spec)\n if match:\n return match.group(1)\n return spec\n\n\ndef package_installed(name: str) -> bool:\n pkg = package_name_from_spec(name)\n try:\n from importlib.metadata import PackageNotFoundError, version\n\n version(pkg)\n return True\n except PackageNotFoundError:\n pass\n except Exception:\n pass\n import_names = {pkg.replace(\"-\", \"_\"), pkg}\n if pkg == \"psycopg2-binary\":\n import_names.add(\"psycopg2\")\n return any(importlib.util.find_spec(c) is not None for c in import_names)\n\n\ndef filter_missing(specs: list[str]) -> list[str]:\n return [s for s in specs if not package_installed(package_name_from_spec(s))]\n\n\ndef install_specs(specs: list[str], dry_run: bool) -> int:\n if not specs:\n return 0\n cmd = [sys.executable, \"-m\", \"pip\", \"install\", *specs]\n print(f\"$ {' '.join(cmd)}\")\n if dry_run:\n return 0\n return subprocess.call(cmd)\n\n\ndef main(argv: list[str]) -> int:\n parser = argparse.ArgumentParser(description=__doc__)\n parser.add_argument(\n \"groups\",\n nargs=\"*\",\n help=\"Optional groups to install. Omit to auto-detect from .env.\",\n )\n parser.add_argument(\n \"--env-file\",\n default=str(DEFAULT_ENV_PATH),\n help=\"Path to .env (default: ./.env, or $BRAINAPI_DOTENV).\",\n )\n parser.add_argument(\n \"--dry-run\", action=\"store_true\",\n help=\"Print the pip command without running it.\",\n )\n parser.add_argument(\n \"--check\", action=\"store_true\",\n help=\"Exit non-zero if any required extras are missing; do not install.\",\n )\n parser.add_argument(\n \"--all\", action=\"store_true\",\n help=\"Install every optional group declared in pyproject.toml.\",\n )\n parser.add_argument(\n \"--include-base\", action=\"store_true\",\n help=\"Also install [project].dependencies / [tool.poetry.dependencies] base deps.\",\n )\n parser.add_argument(\n \"--upgrade-pip\", action=\"store_true\",\n help=\"Run `pip install --upgrade pip` before installing anything.\",\n )\n args = parser.parse_args(argv)\n\n optional_groups = load_optional_groups()\n\n if args.all:\n wanted = list(optional_groups.keys())\n elif args.groups:\n wanted = args.groups\n else:\n env = parse_dotenv(Path(args.env_file))\n wanted = required_groups(env)\n if wanted:\n print(f\"Auto-detected required groups from {args.env_file}: {wanted}\")\n elif not args.include_base:\n print(\n f\"No optional groups required by {args.env_file} \"\n f\"(OCR_MODE={env.get('OCR_MODE', 'docparser')}).\",\n )\n\n unknown = [g for g in wanted if g not in optional_groups]\n known = [g for g in wanted if g in optional_groups]\n if unknown:\n print(\n f\"Skipping optional groups not declared in pyproject.toml: {unknown}\",\n file=sys.stderr,\n )\n if optional_groups:\n print(\n f\"Available optional groups: {list(optional_groups.keys())}\",\n file=sys.stderr,\n )\n else:\n print(\n \"No optional-dependency groups are declared in pyproject.toml. \"\n \"These packages may already be part of base dependencies — \"\n \"continuing without them.\",\n file=sys.stderr,\n )\n\n wanted = known\n extra_specs: list[str] = []\n for g in wanted:\n extra_specs.extend(optional_groups[g])\n\n env = parse_dotenv(Path(args.env_file))\n backend_specs = (\n required_backend_specs(env) if not args.groups and not args.all else []\n )\n\n if args.check:\n missing = filter_missing([*extra_specs, *backend_specs])\n if missing:\n print(f\"Missing extras: {missing}\", file=sys.stderr)\n hint_groups = wanted or (\n [\"postgresql-backend\"] if backend_specs else []\n )\n if hint_groups:\n print(\n f\"Install them with: {sys.executable} \"\n f\"scripts/install_extras.py {' '.join(hint_groups)}\",\n file=sys.stderr,\n )\n return 1\n print(\"All required extras are installed.\")\n return 0\n\n base_specs = load_base_deps() if args.include_base else []\n all_specs = [*base_specs, *extra_specs, *backend_specs]\n\n if not all_specs:\n return 0\n\n if args.upgrade_pip and not args.dry_run:\n subprocess.call([sys.executable, \"-m\", \"pip\", \"install\", \"--upgrade\", \"pip\"])\n\n return install_specs(all_specs, args.dry_run)\n\n\nif __name__ == \"__main__\":\n sys.exit(main(sys.argv[1:]))\n";
diff --git a/tui/src/flows/auth.ts b/tui/src/flows/auth.ts
new file mode 100644
index 0000000..01f919d
--- /dev/null
+++ b/tui/src/flows/auth.ts
@@ -0,0 +1,57 @@
+import { randomBytes } from "node:crypto";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { askPassword, isPromptBack, pickOne, type PromptBack } from "../lib/prompts.js";
+import type { AuthChoices } from "../types.js";
+
+function generateToken(): string {
+ return `brainpat_${randomBytes(24).toString("hex")}`;
+}
+
+export async function askAuth(opts?: { allowBack?: false }): Promise<AuthChoices>;
+export async function askAuth(opts: {
+ allowBack: true;
+ backHint?: string;
+}): Promise<AuthChoices | PromptBack>;
+export async function askAuth(opts?: {
+ allowBack?: boolean;
+ backHint?: string;
+}): Promise<AuthChoices | PromptBack> {
+ p.log.step("Authentication token");
+
+ const action = opts?.allowBack
+ ? await pickOne<"generate" | "paste">({
+ message: "BRAINPAT_TOKEN (used by the API for personal auth)",
+ options: [
+ { value: "generate", label: "Generate one for me" },
+ { value: "paste", label: "Paste my own" },
+ ],
+ initialValue: "generate",
+ allowBack: true,
+ backHint: opts.backHint,
+ })
+ : await pickOne<"generate" | "paste">({
+ message: "BRAINPAT_TOKEN (used by the API for personal auth)",
+ options: [
+ { value: "generate", label: "Generate one for me" },
+ { value: "paste", label: "Paste my own" },
+ ],
+ initialValue: "generate",
+ });
+ if (isPromptBack(action)) {
+ return action;
+ }
+
+ if (action === "generate") {
+ const token = generateToken();
+ p.note(token, "Generated token (saved to .env)");
+ p.log.info(pc.dim("Keep this somewhere safe — it grants API access."));
+ return { brainpatToken: token };
+ }
+
+ const pasted = await askPassword({
+ message: "Paste your BRAINPAT_TOKEN",
+ validate: (value) => (value.trim().length === 0 ? "Token is required" : undefined),
+ });
+ return { brainpatToken: pasted.trim() };
+}
diff --git a/tui/src/flows/connections.ts b/tui/src/flows/connections.ts
new file mode 100644
index 0000000..185c93e
--- /dev/null
+++ b/tui/src/flows/connections.ts
@@ -0,0 +1,226 @@
+import * as p from "@clack/prompts";
+import { SERVICE_DEFAULTS } from "../constants.js";
+import { askPassword, askText, pickOne } from "../lib/prompts.js";
+import type {
+ Connections,
+ DbChoices,
+ MilvusConnection,
+ MongoConnection,
+ Neo4jConnection,
+ PostgresConnection,
+ RedisConnection,
+} from "../types.js";
+
+function portValidator(value: string): string | undefined {
+ const n = Number(value);
+ if (!Number.isInteger(n) || n <= 0 || n > 65535)
+ return "Port must be 1-65535";
+ return undefined;
+}
+
+async function askRedis(): Promise<RedisConnection> {
+ p.log.step("Redis (required for cache + Celery)");
+ const host = await askText({
+ message: "Redis host",
+ placeholder: SERVICE_DEFAULTS.redis.host,
+ defaultValue: SERVICE_DEFAULTS.redis.host,
+ });
+ const port = await askText({
+ message: "Redis port",
+ placeholder: String(SERVICE_DEFAULTS.redis.port),
+ defaultValue: String(SERVICE_DEFAULTS.redis.port),
+ validate: portValidator,
+ });
+ return {
+ host: host.trim() || SERVICE_DEFAULTS.redis.host,
+ port: Number(port) || SERVICE_DEFAULTS.redis.port,
+ };
+}
+
+async function askPostgres(): Promise<PostgresConnection> {
+ p.log.step("PostgreSQL");
+ p.note(
+ [
+ "BrainAPI uses a single Postgres database to host all brains.",
+ "Each brain is isolated logically via a `brain_id` column, not via separate databases.",
+ "Press Enter to accept the default name.",
+ ].join("\n"),
+ "Heads up"
+ );
+ const host = await askText({
+ message: "Postgres host",
+ placeholder: SERVICE_DEFAULTS.postgresql.host,
+ defaultValue: SERVICE_DEFAULTS.postgresql.host,
+ });
+ const port = await askText({
+ message: "Postgres port",
+ placeholder: String(SERVICE_DEFAULTS.postgresql.port),
+ defaultValue: String(SERVICE_DEFAULTS.postgresql.port),
+ validate: portValidator,
+ });
+ const username = await askText({
+ message: "Postgres username",
+ placeholder: SERVICE_DEFAULTS.postgresql.username,
+ defaultValue: SERVICE_DEFAULTS.postgresql.username,
+ });
+ const password = await askPassword({
+ message: "Postgres password (default is 'password')",
+ validate: (value) =>
+ value.length === 0 ? "Password is required" : undefined,
+ });
+ const systemDatabase = await askText({
+ message: `System database (brains registry, default ${SERVICE_DEFAULTS.postgresql.systemDatabase})`,
+ placeholder: SERVICE_DEFAULTS.postgresql.systemDatabase,
+ defaultValue: SERVICE_DEFAULTS.postgresql.systemDatabase,
+ });
+ const maintenanceDatabase = await askText({
+ message: `Maintenance database (for CREATE DATABASE, default ${SERVICE_DEFAULTS.postgresql.maintenanceDatabase})`,
+ placeholder: SERVICE_DEFAULTS.postgresql.maintenanceDatabase,
+ defaultValue: SERVICE_DEFAULTS.postgresql.maintenanceDatabase,
+ });
+ return {
+ host: host.trim() || SERVICE_DEFAULTS.postgresql.host,
+ port: Number(port) || SERVICE_DEFAULTS.postgresql.port,
+ username: username.trim() || SERVICE_DEFAULTS.postgresql.username,
+ password,
+ systemDatabase:
+ systemDatabase.trim() || SERVICE_DEFAULTS.postgresql.systemDatabase,
+ maintenanceDatabase:
+ maintenanceDatabase.trim() ||
+ SERVICE_DEFAULTS.postgresql.maintenanceDatabase,
+ };
+}
+
+async function askNeo4j(): Promise<Neo4jConnection> {
+ p.log.step("Neo4j");
+ const host = await askText({
+ message: "Neo4j host",
+ placeholder: SERVICE_DEFAULTS.neo4j.host,
+ defaultValue: SERVICE_DEFAULTS.neo4j.host,
+ });
+ const port = await askText({
+ message: "Neo4j Bolt port",
+ placeholder: String(SERVICE_DEFAULTS.neo4j.port),
+ defaultValue: String(SERVICE_DEFAULTS.neo4j.port),
+ validate: portValidator,
+ });
+ const username = await askText({
+ message: "Neo4j username",
+ placeholder: SERVICE_DEFAULTS.neo4j.username,
+ defaultValue: SERVICE_DEFAULTS.neo4j.username,
+ });
+ const password = await askPassword({
+ message: "Neo4j password (default is 'your_password')",
+ validate: (value) =>
+ value.length === 0 ? "Password is required" : undefined,
+ });
+ return {
+ host: host.trim() || SERVICE_DEFAULTS.neo4j.host,
+ port: Number(port) || SERVICE_DEFAULTS.neo4j.port,
+ username: username.trim() || SERVICE_DEFAULTS.neo4j.username,
+ password,
+ };
+}
+
+async function askMilvus(): Promise<MilvusConnection> {
+ p.log.step("Milvus");
+ const target = await pickOne<"local" | "managed">({
+ message: "Milvus deployment",
+ options: [
+ { value: "local", label: "Local docker compose" },
+ { value: "managed", label: "Managed (Zilliz Cloud) — uri + token" },
+ ],
+ initialValue: "local",
+ });
+
+ if (target === "managed") {
+ const uri = await askText({
+ message: "Milvus URI",
+ placeholder: "https://your-cluster.api.gcp-us-west1.zillizcloud.com",
+ validate: (value) =>
+ value.trim().length === 0 ? "URI is required" : undefined,
+ });
+ const token = await askPassword({
+ message: "Milvus token",
+ validate: (value) =>
+ value.length === 0 ? "Token is required" : undefined,
+ });
+ return {
+ host: SERVICE_DEFAULTS.milvus.host,
+ port: SERVICE_DEFAULTS.milvus.port,
+ uri: uri.trim(),
+ token,
+ };
+ }
+
+ const host = await askText({
+ message: "Milvus host",
+ placeholder: SERVICE_DEFAULTS.milvus.host,
+ defaultValue: SERVICE_DEFAULTS.milvus.host,
+ });
+ const port = await askText({
+ message: "Milvus port",
+ placeholder: String(SERVICE_DEFAULTS.milvus.port),
+ defaultValue: String(SERVICE_DEFAULTS.milvus.port),
+ validate: portValidator,
+ });
+ return {
+ host: host.trim() || SERVICE_DEFAULTS.milvus.host,
+ port: Number(port) || SERVICE_DEFAULTS.milvus.port,
+ };
+}
+
+async function askMongo(): Promise<MongoConnection> {
+ p.log.step("MongoDB");
+ const host = await askText({
+ message: "Mongo host",
+ placeholder: SERVICE_DEFAULTS.mongo.host,
+ defaultValue: SERVICE_DEFAULTS.mongo.host,
+ });
+ const port = await askText({
+ message: "Mongo port",
+ placeholder: String(SERVICE_DEFAULTS.mongo.port),
+ defaultValue: String(SERVICE_DEFAULTS.mongo.port),
+ validate: portValidator,
+ });
+ const username = await askText({
+ message: "Mongo username",
+ placeholder: SERVICE_DEFAULTS.mongo.username,
+ defaultValue: SERVICE_DEFAULTS.mongo.username,
+ });
+ const password = await askPassword({
+ message: "Mongo password (default is 'password')",
+ validate: (value) =>
+ value.length === 0 ? "Password is required" : undefined,
+ });
+ return {
+ host: host.trim() || SERVICE_DEFAULTS.mongo.host,
+ port: Number(port) || SERVICE_DEFAULTS.mongo.port,
+ username: username.trim() || SERVICE_DEFAULTS.mongo.username,
+ password,
+ };
+}
+
+export async function askConnections(dbs: DbChoices): Promise<Connections> {
+ const redis = await askRedis();
+ const result: Connections = { redis };
+
+ const needsPostgres =
+ dbs.vectorDb === "postgresql" ||
+ dbs.dataDb === "postgresql" ||
+ dbs.graphDb === "networkx";
+ if (needsPostgres) {
+ result.postgresql = await askPostgres();
+ }
+ if (dbs.graphDb === "neo4j") {
+ result.neo4j = await askNeo4j();
+ }
+ if (dbs.vectorDb === "milvus") {
+ result.milvus = await askMilvus();
+ }
+ if (dbs.dataDb === "mongo") {
+ result.mongo = await askMongo();
+ }
+
+ return result;
+}
diff --git a/tui/src/flows/defaults.ts b/tui/src/flows/defaults.ts
new file mode 100644
index 0000000..8787747
--- /dev/null
+++ b/tui/src/flows/defaults.ts
@@ -0,0 +1,78 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import {
+ askConfirm,
+ askConfirmOrBack,
+ isPromptBack,
+ pickOne,
+ type PromptBack,
+} from "../lib/prompts.js";
+import type { DbChoices } from "../types.js";
+
+export async function askUseDefaults(opts?: {
+ allowBack?: false;
+}): Promise<boolean>;
+export async function askUseDefaults(opts: {
+ allowBack: true;
+ backHint?: string;
+}): Promise<boolean | PromptBack>;
+export async function askUseDefaults(opts?: {
+ allowBack?: boolean;
+ backHint?: string;
+}): Promise<boolean | PromptBack> {
+ const choice = opts?.allowBack
+ ? await pickOne<"defaults" | "custom">({
+ message: "How would you like to configure BrainAPI?",
+ options: [
+ { value: "defaults", label: "Use default settings", hint: "Postgres + pgvector + NetworkX + remote LLM" },
+ { value: "custom", label: "Configure each option manually" },
+ ],
+ initialValue: "defaults",
+ allowBack: true,
+ backHint: opts.backHint,
+ })
+ : await pickOne<"defaults" | "custom">({
+ message: "How would you like to configure BrainAPI?",
+ options: [
+ { value: "defaults", label: "Use default settings", hint: "Postgres + pgvector + NetworkX + remote LLM" },
+ { value: "custom", label: "Configure each option manually" },
+ ],
+ initialValue: "defaults",
+ });
+
+ if (isPromptBack(choice)) {
+ return choice;
+ }
+
+ if (choice === "custom") return false;
+
+ p.note(
+ [
+ "Stack: NetworkX (on Postgres) + pgvector + Postgres data layer + remote LLM.",
+ "Backing services: " + pc.cyan("Redis") + " + " + pc.cyan("Postgres") + ".",
+ "",
+ "You'll still be asked how to run those services (Docker or manual),",
+ "for the remote LLM provider, GCP credentials, and a BRAINPAT_TOKEN.",
+ ].join("\n"),
+ "Defaults",
+ );
+
+ if (opts?.allowBack) {
+ return askConfirmOrBack({
+ message: "Continue with defaults?",
+ initialValue: true,
+ backHint: opts.backHint,
+ });
+ }
+
+ return askConfirm({
+ message: "Continue with defaults?",
+ initialValue: true,
+ });
+}
+
+export const DEFAULT_DBS: DbChoices = {
+ vectorDb: "postgresql",
+ dataDb: "postgresql",
+ graphDb: "networkx",
+};
diff --git a/tui/src/flows/embedding-dimensions.ts b/tui/src/flows/embedding-dimensions.ts
new file mode 100644
index 0000000..11da988
--- /dev/null
+++ b/tui/src/flows/embedding-dimensions.ts
@@ -0,0 +1,145 @@
+import * as p from "@clack/prompts";
+import {
+ AZURE_DEFAULT_EMBEDDING_MODEL,
+ BEDROCK_DEFAULT_EMBEDDING_MODEL,
+ EMBEDDINGS_DEFAULTS,
+ GCP_DEFAULT_EMBEDDING_MODEL,
+ KNOWN_EMBEDDING_MODEL_DIMENSIONS,
+ lookupEmbeddingDimensions,
+ OPENAI_DEFAULT_EMBEDDING_MODEL,
+} from "../constants.js";
+import {
+ askConfirm,
+ askConfirmOrBack,
+ askText,
+ isPromptBack,
+ type PromptBack,
+} from "../lib/prompts.js";
+import type { EmbeddingDimensions, ModelsChoices, ModelProvider } from "../types.js";
+
+function dimensionsFromSize(size: number): EmbeddingDimensions {
+ return {
+ nodesDimension: size,
+ tripletsDimension: size,
+ observationsDimension: size,
+ dataDimension: size,
+ relationshipsDimension: size,
+ };
+}
+
+async function askDimensionSize(initial?: number): Promise<number> {
+ const raw = await askText({
+ message: "Embedding vector dimensions",
+ placeholder: initial ? String(initial) : "3072",
+ defaultValue: initial ? String(initial) : "3072",
+ validate: (value) => {
+ const n = Number(value.trim());
+ if (!Number.isInteger(n) || n <= 0) {
+ return "Enter a positive whole number";
+ }
+ return undefined;
+ },
+ });
+ const n = Number(raw.trim());
+ if (!Number.isInteger(n) || n <= 0) {
+ throw new Error("Invalid embedding dimensions");
+ }
+ return n;
+}
+
+export async function askEmbeddingDimensions(
+ embeddingModel: string,
+ opts?: {
+ allowBack?: boolean;
+ backHint?: string;
+ initial?: EmbeddingDimensions;
+ },
+): Promise<EmbeddingDimensions | PromptBack> {
+ p.log.step("Embedding dimensions");
+ const known = lookupEmbeddingDimensions(embeddingModel);
+ const initialSize =
+ opts?.initial?.nodesDimension ?? known ?? EMBEDDINGS_DEFAULTS.nodesDimension;
+
+ if (known !== undefined) {
+ p.note(
+ [
+ `Model: ${embeddingModel}`,
+ `Known output size: ${known} dimensions`,
+ "",
+ "All vector stores (nodes, triplets, observations, data, relationships)",
+ "must use the same dimension as your embedding model.",
+ ].join("\n"),
+ "Embedding dimensions",
+ );
+
+ if (opts?.allowBack) {
+ const picked = await askConfirmOrBack({
+ message: `Use ${known} dimensions for all embedding vector stores?`,
+ initialValue: true,
+ backHint: opts.backHint,
+ });
+ if (isPromptBack(picked)) {
+ return picked;
+ }
+ if (picked) {
+ return dimensionsFromSize(known);
+ }
+ } else {
+ const useKnown = await askConfirm({
+ message: `Use ${known} dimensions for all embedding vector stores?`,
+ initialValue: true,
+ });
+ if (useKnown) {
+ return dimensionsFromSize(known);
+ }
+ }
+ } else {
+ p.note(
+ [
+ `Model: ${embeddingModel}`,
+ "This model is not in the built-in dimension map.",
+ "Enter the embedding output size from your provider docs.",
+ ].join("\n"),
+ "Embedding dimensions",
+ );
+ }
+
+ const size = await askDimensionSize(initialSize);
+ return dimensionsFromSize(size);
+}
+
+export function resolveActiveEmbeddingModel(models: ModelsChoices): string {
+ const provider: ModelProvider = models.embeddingsProvider;
+ switch (provider) {
+ case "ollama":
+ return models.ollama?.embeddingsLocalModel ?? EMBEDDINGS_DEFAULTS.localModel;
+ case "openai":
+ return models.openai?.embeddingModel ?? OPENAI_DEFAULT_EMBEDDING_MODEL;
+ case "azure":
+ return models.azure?.embeddingModel ?? AZURE_DEFAULT_EMBEDDING_MODEL;
+ case "gcp_vertex":
+ return models.gcp?.embeddingModel ?? GCP_DEFAULT_EMBEDDING_MODEL;
+ case "amazon_bedrock":
+ return models.bedrock?.embeddingModel ?? BEDROCK_DEFAULT_EMBEDDING_MODEL;
+ default:
+ return EMBEDDINGS_DEFAULTS.localModel;
+ }
+}
+
+export async function attachEmbeddingDimensions(
+ models: ModelsChoices,
+ opts?: {
+ allowBack?: boolean;
+ backHint?: string;
+ initial?: EmbeddingDimensions;
+ },
+): Promise<ModelsChoices | PromptBack> {
+ const embeddingModel = resolveActiveEmbeddingModel(models);
+ const dimensions = await askEmbeddingDimensions(embeddingModel, opts);
+ if (isPromptBack(dimensions)) {
+ return dimensions;
+ }
+ return { ...models, embeddingDimensions: dimensions };
+}
+
+export { KNOWN_EMBEDDING_MODEL_DIMENSIONS };
diff --git a/tui/src/flows/models.ts b/tui/src/flows/models.ts
new file mode 100644
index 0000000..b4d66dc
--- /dev/null
+++ b/tui/src/flows/models.ts
@@ -0,0 +1,391 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { homedir } from "node:os";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import {
+ AZURE_DEFAULT_EMBEDDING_MODEL,
+ AZURE_DEFAULT_SMALL_MODEL,
+ AZURE_DEFAULT_LARGE_API_VERSION,
+ AZURE_DEFAULT_LARGE_MODEL,
+ BEDROCK_DEFAULT_EMBEDDING_MODEL,
+ BEDROCK_DEFAULT_LARGE_MODEL,
+ BEDROCK_DEFAULT_REGION,
+ BEDROCK_DEFAULT_SMALL_MODEL,
+ GCP_DEFAULT_EMBEDDING_MODEL,
+ GCP_DEFAULT_LARGE_MODEL,
+ GCP_DEFAULT_SMALL_MODEL,
+ OPENAI_DEFAULT_EMBEDDING_MODEL,
+ OPENAI_DEFAULT_LARGE_MODEL,
+ OPENAI_DEFAULT_SMALL_MODEL,
+} from "../constants.js";
+import {
+ askPassword,
+ askText,
+ isPromptBack,
+ pickOne,
+ type PromptBack,
+} from "../lib/prompts.js";
+import type {
+ AzureChoices,
+ BedrockChoices,
+ GcpChoices,
+ ModelProvider,
+ ModelsChoices,
+ ModelsMode,
+ OpenAIChoices,
+} from "../types.js";
+import { askOllama } from "./ollama.js";
+import { attachEmbeddingDimensions } from "./embedding-dimensions.js";
+
+function expandHome(filePath: string): string {
+ if (filePath.startsWith("~")) {
+ return path.join(homedir(), filePath.slice(1));
+ }
+ return filePath;
+}
+
+interface GcpCredentialsCheck {
+ error?: string;
+ projectId?: string;
+}
+
+async function inspectGcpCredentials(filePath: string): Promise<GcpCredentialsCheck> {
+ const expanded = expandHome(filePath.trim());
+ if (!expanded) return { error: "Path is required" };
+ try {
+ const info = await stat(expanded);
+ if (!info.isFile()) return { error: "Path is not a file" };
+ const raw = await readFile(expanded, "utf8");
+ const parsed = JSON.parse(raw) as { project_id?: unknown };
+ const projectId =
+ typeof parsed.project_id === "string" && parsed.project_id.trim().length > 0
+ ? parsed.project_id.trim()
+ : undefined;
+ return { projectId };
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ return { error: `Could not read credentials JSON: ${message}` };
+ }
+}
+
+async function askGcp(): Promise<GcpChoices> {
+ p.log.step("Configure GCP Vertex");
+
+ let credentialsPath = "";
+ let projectIdFromFile: string | undefined;
+ while (true) {
+ const raw = await askText({
+ message: "Path to GCP service-account credentials JSON",
+ placeholder: "~/.config/gcloud/brainapi.json",
+ });
+ const result = await inspectGcpCredentials(raw);
+ if (!result.error) {
+ credentialsPath = expandHome(raw.trim());
+ projectIdFromFile = result.projectId;
+ break;
+ }
+ p.log.error(result.error);
+ }
+
+ let projectId: string;
+ if (projectIdFromFile) {
+ projectId = projectIdFromFile;
+ p.log.info(`Using GCP project ${pc.cyan(projectId)} (from credentials file)`);
+ } else {
+ p.log.warn(
+ "No project_id field found in the credentials JSON — please enter it manually.",
+ );
+ const entered = await askText({
+ message: "GCP project id",
+ placeholder: "my-gcp-project",
+ validate: (value) => (value.trim().length === 0 ? "Project id is required" : undefined),
+ });
+ projectId = entered.trim();
+ }
+
+ const smallModel = await askText({
+ message: "GCP small LLM model",
+ placeholder: GCP_DEFAULT_SMALL_MODEL,
+ defaultValue: GCP_DEFAULT_SMALL_MODEL,
+ });
+ const largeModel = await askText({
+ message: "GCP large LLM model",
+ placeholder: GCP_DEFAULT_LARGE_MODEL,
+ defaultValue: GCP_DEFAULT_LARGE_MODEL,
+ });
+ const embeddingModel = await askText({
+ message: "GCP embedding model",
+ placeholder: GCP_DEFAULT_EMBEDDING_MODEL,
+ defaultValue: GCP_DEFAULT_EMBEDDING_MODEL,
+ });
+
+ return {
+ credentialsPath,
+ projectId,
+ smallLlmModel: smallModel.trim() || GCP_DEFAULT_SMALL_MODEL,
+ largeLlmModel: largeModel.trim() || GCP_DEFAULT_LARGE_MODEL,
+ embeddingModel: embeddingModel.trim() || GCP_DEFAULT_EMBEDDING_MODEL,
+ };
+}
+
+async function askAzure(): Promise<AzureChoices> {
+ p.log.step("Configure Azure OpenAI");
+ const llmEndpoint = await askText({
+ message: "Azure LLM endpoint",
+ placeholder: "https://yourproject.openai.azure.com",
+ validate: (value) => (value.trim().length === 0 ? "Endpoint is required" : undefined),
+ });
+ const llmApiVersion = await askText({
+ message: "Azure LLM API version",
+ placeholder: AZURE_DEFAULT_LARGE_API_VERSION,
+ defaultValue: AZURE_DEFAULT_LARGE_API_VERSION,
+ });
+ const llmSubscriptionKey = await askPassword({
+ message: "Azure LLM subscription key",
+ validate: (value) => (value.trim().length === 0 ? "API key is required" : undefined),
+ });
+ const smallLlmModel = await askText({
+ message: "Azure small LLM deployment/model",
+ placeholder: AZURE_DEFAULT_SMALL_MODEL,
+ defaultValue: AZURE_DEFAULT_SMALL_MODEL,
+ });
+ const largeLlmModel = await askText({
+ message: "Azure large LLM deployment/model",
+ placeholder: AZURE_DEFAULT_LARGE_MODEL,
+ defaultValue: AZURE_DEFAULT_LARGE_MODEL,
+ });
+ const embeddingEndpoint = await askText({
+ message: "Azure embeddings endpoint URL",
+ placeholder:
+ "https://yourproject.openai.azure.com/openai/deployments/text-embedding-3-large/embeddings?api-version=2023-05-15",
+ validate: (value) => (value.trim().length === 0 ? "Endpoint URL is required" : undefined),
+ });
+ const embeddingKey = await askPassword({
+ message: "Azure embeddings API key",
+ validate: (value) => (value.trim().length === 0 ? "API key is required" : undefined),
+ });
+ const embeddingModel = await askText({
+ message: "Azure embedding model/deployment",
+ placeholder: AZURE_DEFAULT_EMBEDDING_MODEL,
+ defaultValue: AZURE_DEFAULT_EMBEDDING_MODEL,
+ });
+
+ return {
+ smallLlmModel: smallLlmModel.trim() || AZURE_DEFAULT_SMALL_MODEL,
+ largeLlmModel: largeLlmModel.trim() || AZURE_DEFAULT_LARGE_MODEL,
+ llmApiVersion: llmApiVersion.trim() || AZURE_DEFAULT_LARGE_API_VERSION,
+ llmEndpoint: llmEndpoint.trim(),
+ llmSubscriptionKey: llmSubscriptionKey.trim(),
+ embeddingEndpoint: embeddingEndpoint.trim(),
+ embeddingKey: embeddingKey.trim(),
+ embeddingModel: embeddingModel.trim() || AZURE_DEFAULT_EMBEDDING_MODEL,
+ };
+}
+
+async function askBedrock(): Promise<BedrockChoices> {
+ p.log.step("Configure Amazon Bedrock");
+ const region = await askText({
+ message: "AWS region",
+ placeholder: BEDROCK_DEFAULT_REGION,
+ defaultValue: BEDROCK_DEFAULT_REGION,
+ });
+ const accessKeyId = await askText({
+ message: "AWS access key id",
+ validate: (value) =>
+ value.trim().length === 0 ? "Access key id is required" : undefined,
+ });
+ const secretAccessKey = await askPassword({
+ message: "AWS secret access key",
+ validate: (value) =>
+ value.trim().length === 0 ? "Secret access key is required" : undefined,
+ });
+ const sessionToken = await askPassword({
+ message: "AWS session token (optional)",
+ validate: () => undefined,
+ });
+ const smallLlmModel = await askText({
+ message: "Bedrock small LLM model id",
+ placeholder: BEDROCK_DEFAULT_SMALL_MODEL,
+ defaultValue: BEDROCK_DEFAULT_SMALL_MODEL,
+ });
+ const largeLlmModel = await askText({
+ message: "Bedrock large LLM model id",
+ placeholder: BEDROCK_DEFAULT_LARGE_MODEL,
+ defaultValue: BEDROCK_DEFAULT_LARGE_MODEL,
+ });
+ const embeddingModel = await askText({
+ message: "Bedrock embedding model id",
+ placeholder: BEDROCK_DEFAULT_EMBEDDING_MODEL,
+ defaultValue: BEDROCK_DEFAULT_EMBEDDING_MODEL,
+ });
+ return {
+ region: region.trim() || BEDROCK_DEFAULT_REGION,
+ accessKeyId: accessKeyId.trim(),
+ secretAccessKey: secretAccessKey.trim(),
+ sessionToken: sessionToken.trim() || undefined,
+ smallLlmModel: smallLlmModel.trim() || BEDROCK_DEFAULT_SMALL_MODEL,
+ largeLlmModel: largeLlmModel.trim() || BEDROCK_DEFAULT_LARGE_MODEL,
+ embeddingModel: embeddingModel.trim() || BEDROCK_DEFAULT_EMBEDDING_MODEL,
+ };
+}
+
+async function askOpenAI(): Promise<OpenAIChoices> {
+ p.log.step("Configure OpenAI");
+
+ const apiKey = await askPassword({
+ message: "OpenAI API key",
+ validate: (value) =>
+ value.trim().length === 0 ? "API key is required" : undefined,
+ });
+ const baseUrl = await askText({
+ message: "OpenAI base URL (optional)",
+ placeholder: "https://api.openai.com/v1",
+ defaultValue: "",
+ });
+ const smallLlmModel = await askText({
+ message: "OpenAI small LLM model",
+ placeholder: OPENAI_DEFAULT_SMALL_MODEL,
+ defaultValue: OPENAI_DEFAULT_SMALL_MODEL,
+ });
+ const largeLlmModel = await askText({
+ message: "OpenAI large LLM model",
+ placeholder: OPENAI_DEFAULT_LARGE_MODEL,
+ defaultValue: OPENAI_DEFAULT_LARGE_MODEL,
+ });
+ const embeddingModel = await askText({
+ message: "OpenAI embedding model",
+ placeholder: OPENAI_DEFAULT_EMBEDDING_MODEL,
+ defaultValue: OPENAI_DEFAULT_EMBEDDING_MODEL,
+ });
+
+ return {
+ apiKey: apiKey.trim(),
+ baseUrl: baseUrl.trim() || undefined,
+ smallLlmModel: smallLlmModel.trim() || OPENAI_DEFAULT_SMALL_MODEL,
+ largeLlmModel: largeLlmModel.trim() || OPENAI_DEFAULT_LARGE_MODEL,
+ embeddingModel: embeddingModel.trim() || OPENAI_DEFAULT_EMBEDDING_MODEL,
+ };
+}
+
+async function askProvider(message: string, initialValue: ModelProvider): Promise<ModelProvider> {
+ return pickOne<ModelProvider>({
+ message,
+ options: [
+ { value: "ollama", label: "Ollama" },
+ { value: "openai", label: "OpenAI" },
+ { value: "azure", label: "Azure OpenAI" },
+ { value: "gcp_vertex", label: "Google Cloud — Vertex AI" },
+ { value: "amazon_bedrock", label: "Amazon Bedrock" },
+ ],
+ initialValue,
+ });
+}
+
+export async function askModels(options?: {
+ prechosenMode?: ModelsMode;
+ allowBack?: false;
+ initialMode?: ModelsMode;
+}): Promise<ModelsChoices>;
+export async function askModels(options: {
+ prechosenMode?: ModelsMode;
+ allowBack: true;
+ backHint?: string;
+ initialMode?: ModelsMode;
+}): Promise<ModelsChoices | PromptBack>;
+export async function askModels(options?: {
+ prechosenMode?: ModelsMode;
+ allowBack?: boolean;
+ backHint?: string;
+ initialMode?: ModelsMode;
+}): Promise<ModelsChoices | PromptBack> {
+ let mode = options?.prechosenMode;
+ if (!mode) {
+ const picked = options?.allowBack
+ ? await pickOne<ModelsMode>({
+ message: "Models mode",
+ options: [
+ { value: "remote", label: "Remote (cloud provider)" },
+ { value: "local", label: "Local (Ollama)" },
+ ],
+ initialValue: options.initialMode ?? "remote",
+ allowBack: true,
+ backHint: options.backHint,
+ })
+ : await pickOne<ModelsMode>({
+ message: "Models mode",
+ options: [
+ { value: "remote", label: "Remote (cloud provider)" },
+ { value: "local", label: "Local (Ollama)" },
+ ],
+ initialValue: options?.initialMode ?? "remote",
+ });
+ if (isPromptBack(picked)) {
+ return picked;
+ }
+ mode = picked;
+ }
+
+ if (mode === "local") {
+ const ollama = await askOllama();
+ return attachEmbeddingDimensions(
+ {
+ mode,
+ llmSmallProvider: "ollama",
+ llmLargeProvider: "ollama",
+ embeddingsProvider: "ollama",
+ ollama,
+ },
+ {
+ allowBack: options?.allowBack,
+ backHint: options?.backHint,
+ },
+ );
+ }
+
+ const llmSmallProvider = await askProvider("Small LLM provider", "gcp_vertex");
+ const llmLargeProvider = await askProvider("Large LLM provider", "azure");
+ const embeddingsProvider = await askProvider("Embeddings provider", "azure");
+
+ const providers = new Set([llmSmallProvider, llmLargeProvider, embeddingsProvider]);
+
+ let ollama = undefined;
+ let gcp = undefined;
+ let azure = undefined;
+ let openai = undefined;
+ let bedrock = undefined;
+
+ if (providers.has("ollama")) {
+ ollama = await askOllama();
+ }
+ if (providers.has("gcp_vertex")) {
+ gcp = await askGcp();
+ }
+ if (providers.has("azure")) {
+ azure = await askAzure();
+ }
+ if (providers.has("openai")) {
+ openai = await askOpenAI();
+ }
+ if (providers.has("amazon_bedrock")) {
+ bedrock = await askBedrock();
+ }
+
+ return attachEmbeddingDimensions(
+ {
+ mode,
+ llmSmallProvider,
+ llmLargeProvider,
+ embeddingsProvider,
+ ollama,
+ gcp,
+ azure,
+ openai,
+ bedrock,
+ },
+ {
+ allowBack: options?.allowBack,
+ backHint: options?.backHint,
+ },
+ );
+}
diff --git a/tui/src/flows/ollama.ts b/tui/src/flows/ollama.ts
new file mode 100644
index 0000000..2019ca9
--- /dev/null
+++ b/tui/src/flows/ollama.ts
@@ -0,0 +1,174 @@
+import { access } from "node:fs/promises";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import {
+ OLLAMA_DEFAULT_HOST,
+ OLLAMA_DEFAULT_LARGE_MODEL,
+ OLLAMA_DEFAULT_PORT,
+ OLLAMA_DEFAULT_SMALL_MODEL,
+ EMBEDDINGS_DEFAULTS,
+} from "../constants.js";
+import {
+ hasOllamaModel,
+ isOllamaRunning,
+ pullOllamaModel,
+ type OllamaTarget,
+} from "../lib/ollama.js";
+import { askConfirm, askText, pickOne } from "../lib/prompts.js";
+import type { OllamaChoices } from "../types.js";
+
+async function waitForRunning(target: OllamaTarget): Promise<void> {
+ while (!(await isOllamaRunning(target))) {
+ p.log.warn(
+ `Ollama did not respond at ${pc.cyan(`http://${target.host}:${target.port}`)}.`,
+ );
+ p.note(
+ [
+ "Start Ollama in a separate terminal:",
+ " ollama serve",
+ "Or launch the Ollama desktop app.",
+ ].join("\n"),
+ "Ollama not running",
+ );
+ await askConfirm({
+ message: "Press enter when Ollama is running",
+ initialValue: true,
+ });
+ }
+ p.log.success("Ollama is up.");
+}
+
+type MissingModelAction = "pull" | "change";
+
+async function waitForModel(
+ target: OllamaTarget,
+ initialModelName: string,
+ role: "small" | "large",
+): Promise<string> {
+ let modelName = initialModelName;
+ while (!(await hasOllamaModel(target, modelName))) {
+ p.log.warn(`Model ${pc.cyan(modelName)} is not available locally.`);
+
+ const action = await pickOne<MissingModelAction>({
+ message: `How do you want to provide the ${role} model?`,
+ options: [
+ {
+ value: "pull",
+ label: "Pull this model now",
+ hint: `runs: ollama pull ${modelName}`,
+ },
+ {
+ value: "change",
+ label: "Use a different model name",
+ },
+ ],
+ initialValue: "pull",
+ });
+
+ if (action === "pull") {
+ const spinner = p.spinner();
+ spinner.start(`Pulling ${modelName}`);
+ const result = await pullOllamaModel(modelName);
+ if (result.ok) {
+ spinner.stop(`Pulled ${pc.cyan(modelName)}`);
+ if (await hasOllamaModel(target, modelName)) {
+ continue;
+ }
+ p.log.warn(
+ `Pull finished but ${pc.cyan(modelName)} is still not listed by Ollama. Check the tag name.`,
+ );
+ continue;
+ }
+ spinner.stop(pc.red(`Failed to pull ${modelName}`));
+ p.log.error(result.error ?? `ollama pull exited with code ${result.exitCode}`);
+ continue;
+ }
+
+ const nextModel = await askText({
+ message: `${role[0]!.toUpperCase()}${role.slice(1)} model name (Ollama tag)`,
+ placeholder: modelName,
+ defaultValue: modelName,
+ validate: (value) =>
+ value.trim().length === 0 ? "Model name is required" : undefined,
+ });
+ modelName = nextModel.trim();
+ }
+ p.log.success(`Model ${pc.cyan(modelName)} is available.`);
+ return modelName;
+}
+
+async function askEmbeddingsLocal(defaultModel: string): Promise<string> {
+ const raw = await askText({
+ message: "Local sentence-transformers embeddings model",
+ placeholder: defaultModel,
+ defaultValue: defaultModel,
+ });
+ return raw.trim() || defaultModel;
+}
+
+export async function askOllama(): Promise<OllamaChoices> {
+ p.log.step("Configure Ollama");
+
+ const hostRaw = await askText({
+ message: "Ollama host",
+ placeholder: OLLAMA_DEFAULT_HOST,
+ defaultValue: OLLAMA_DEFAULT_HOST,
+ });
+ const portRaw = await askText({
+ message: "Ollama port",
+ placeholder: String(OLLAMA_DEFAULT_PORT),
+ defaultValue: String(OLLAMA_DEFAULT_PORT),
+ validate: (value) => {
+ const n = Number(value);
+ if (!Number.isInteger(n) || n <= 0 || n > 65535) return "Port must be 1-65535";
+ return undefined;
+ },
+ });
+ const target: OllamaTarget = {
+ host: hostRaw.trim() || OLLAMA_DEFAULT_HOST,
+ port: Number(portRaw) || OLLAMA_DEFAULT_PORT,
+ };
+
+ await waitForRunning(target);
+
+ const smallModelRaw = await askText({
+ message: "Small LLM model name (Ollama tag)",
+ placeholder: OLLAMA_DEFAULT_SMALL_MODEL,
+ defaultValue: OLLAMA_DEFAULT_SMALL_MODEL,
+ });
+ const smallModel = await waitForModel(
+ target,
+ smallModelRaw.trim() || OLLAMA_DEFAULT_SMALL_MODEL,
+ "small",
+ );
+
+ const largeModelRaw = await askText({
+ message: "Large LLM model name (Ollama tag)",
+ placeholder: OLLAMA_DEFAULT_LARGE_MODEL,
+ defaultValue: OLLAMA_DEFAULT_LARGE_MODEL,
+ });
+ const largeModel = await waitForModel(
+ target,
+ largeModelRaw.trim() || OLLAMA_DEFAULT_LARGE_MODEL,
+ "large",
+ );
+
+ const embeddingsLocalModel = await askEmbeddingsLocal(EMBEDDINGS_DEFAULTS.localModel);
+
+ return {
+ host: target.host,
+ port: target.port,
+ smallModel,
+ largeModel,
+ embeddingsLocalModel,
+ };
+}
+
+export async function isFileReadable(filePath: string): Promise<boolean> {
+ try {
+ await access(filePath);
+ return true;
+ } catch {
+ return false;
+ }
+}
diff --git a/tui/src/flows/pipeline.ts b/tui/src/flows/pipeline.ts
new file mode 100644
index 0000000..54241e1
--- /dev/null
+++ b/tui/src/flows/pipeline.ts
@@ -0,0 +1,92 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { isPromptBack, pickOne, type PromptBack } from "../lib/prompts.js";
+import type { OcrMode, PipelineChoices } from "../types.js";
+
+export async function askPipeline(options?: {
+ prechosenOcrMode?: OcrMode;
+ allowBack?: false;
+ initialOcrMode?: OcrMode;
+}): Promise<PipelineChoices>;
+export async function askPipeline(options: {
+ prechosenOcrMode?: OcrMode;
+ allowBack: true;
+ backHint?: string;
+ initialOcrMode?: OcrMode;
+}): Promise<PipelineChoices | PromptBack>;
+export async function askPipeline(options?: {
+ prechosenOcrMode?: OcrMode;
+ allowBack?: boolean;
+ backHint?: string;
+ initialOcrMode?: OcrMode;
+}): Promise<PipelineChoices | PromptBack> {
+ if (options?.prechosenOcrMode) {
+ return { ocrMode: options.prechosenOcrMode };
+ }
+
+ p.log.step("Document ingestion");
+ const ocrMode = options?.allowBack
+ ? await pickOne<OcrMode>({
+ message: "OCR engine for document parsing",
+ options: [
+ {
+ value: "docparser",
+ label: "Remote DocParser (default)",
+ hint: "lightweight install, calls Lumen DocParser API",
+ },
+ {
+ value: "docling",
+ label: "Local Docling",
+ hint: "adds ~2 GB ML deps (docling, accelerate)",
+ },
+ ],
+ initialValue: options.initialOcrMode ?? "docparser",
+ allowBack: true,
+ backHint: options.backHint,
+ })
+ : await pickOne<OcrMode>({
+ message: "OCR engine for document parsing",
+ options: [
+ {
+ value: "docparser",
+ label: "Remote DocParser (default)",
+ hint: "lightweight install, calls Lumen DocParser API",
+ },
+ {
+ value: "docling",
+ label: "Local Docling",
+ hint: "adds ~2 GB ML deps (docling, accelerate)",
+ },
+ ],
+ initialValue: options?.initialOcrMode ?? "docparser",
+ });
+ if (isPromptBack(ocrMode)) {
+ return ocrMode;
+ }
+
+ if (ocrMode === "docling") {
+ p.log.info(
+ pc.dim(
+ "Docling and accelerate will be installed into the venv after this flow.",
+ ),
+ );
+ }
+
+ return { ocrMode };
+}
+
+export function ocrToExtras(ocrMode: OcrMode): string[] {
+ return ocrMode === "docling" ? ["docling-ocr"] : [];
+}
+
+export function postgresBackendExtras(dbs: {
+ vectorDb: string;
+ dataDb: string;
+ graphDb: string;
+}): string[] {
+ const needs =
+ dbs.vectorDb === "postgresql" ||
+ dbs.dataDb === "postgresql" ||
+ dbs.graphDb === "networkx";
+ return needs ? ["postgresql-backend"] : [];
+}
diff --git a/tui/src/flows/services-runtime.ts b/tui/src/flows/services-runtime.ts
new file mode 100644
index 0000000..67c4247
--- /dev/null
+++ b/tui/src/flows/services-runtime.ts
@@ -0,0 +1,91 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { isPromptBack, pickOne, type PromptBack } from "../lib/prompts.js";
+import type { DbChoices, ServicesRuntime } from "../types.js";
+
+function nonRedisPicked(dbs: DbChoices): string[] {
+ const picked: string[] = [];
+ if (
+ dbs.vectorDb === "postgresql" ||
+ dbs.dataDb === "postgresql" ||
+ dbs.graphDb === "networkx"
+ ) {
+ picked.push("PostgreSQL");
+ }
+ if (dbs.graphDb === "neo4j") picked.push("Neo4j");
+ if (dbs.vectorDb === "milvus") picked.push("Milvus");
+ if (dbs.dataDb === "mongo") picked.push("MongoDB");
+ return picked;
+}
+
+export async function askServicesRuntime(
+ dbs: DbChoices,
+ opts?: { allowBack?: false; initialValue?: ServicesRuntime },
+): Promise<ServicesRuntime>;
+export async function askServicesRuntime(
+ dbs: DbChoices,
+ opts: {
+ allowBack: true;
+ backHint?: string;
+ initialValue?: ServicesRuntime;
+ },
+): Promise<ServicesRuntime | PromptBack>;
+export async function askServicesRuntime(
+ dbs: DbChoices,
+ opts?: {
+ allowBack?: boolean;
+ backHint?: string;
+ initialValue?: ServicesRuntime;
+ },
+): Promise<ServicesRuntime | PromptBack> {
+ const sidecars = ["Redis", ...nonRedisPicked(dbs)];
+ p.note(
+ [
+ `BrainAPI needs these backing services for your setup:`,
+ ` ${pc.cyan(sidecars.join(", "))}`,
+ ``,
+ `You can let BrainAPI manage them via Docker, or run them yourself.`,
+ ].join("\n"),
+ "Backing services",
+ );
+
+ const picked = opts?.allowBack
+ ? await pickOne<ServicesRuntime>({
+ message: "How do you want to run them?",
+ options: [
+ {
+ value: "docker",
+ label: "Docker Compose (recommended)",
+ hint: "isolated, reproducible, one extra dependency",
+ },
+ {
+ value: "manual",
+ label: "Manual — I'll install/run them myself",
+ hint: "no Docker dependency; the TUI just probes for reachability",
+ },
+ ],
+ initialValue: opts.initialValue ?? "docker",
+ allowBack: true,
+ backHint: opts.backHint,
+ })
+ : await pickOne<ServicesRuntime>({
+ message: "How do you want to run them?",
+ options: [
+ {
+ value: "docker",
+ label: "Docker Compose (recommended)",
+ hint: "isolated, reproducible, one extra dependency",
+ },
+ {
+ value: "manual",
+ label: "Manual — I'll install/run them myself",
+ hint: "no Docker dependency; the TUI just probes for reachability",
+ },
+ ],
+ initialValue: opts?.initialValue ?? "docker",
+ });
+ if (isPromptBack(picked)) {
+ return picked;
+ }
+ return picked;
+}
diff --git a/tui/src/flows/services.ts b/tui/src/flows/services.ts
new file mode 100644
index 0000000..b9ec497
--- /dev/null
+++ b/tui/src/flows/services.ts
@@ -0,0 +1,90 @@
+import * as p from "@clack/prompts";
+import { isPromptBack, pickOne, type PromptBack } from "../lib/prompts.js";
+import type { DbChoices } from "../types.js";
+
+export async function askDatabases(opts?: {
+ allowBack?: false;
+ initial?: Partial<DbChoices>;
+}): Promise<DbChoices>;
+export async function askDatabases(opts: {
+ allowBack: true;
+ backHint?: string;
+ initial?: Partial<DbChoices>;
+}): Promise<DbChoices | PromptBack>;
+export async function askDatabases(opts?: {
+ allowBack?: boolean;
+ backHint?: string;
+ initial?: Partial<DbChoices>;
+}): Promise<DbChoices | PromptBack> {
+ p.log.step("Pick your databases");
+
+ let vectorDb = opts?.initial?.vectorDb ?? "postgresql";
+ let dataDb = opts?.initial?.dataDb ?? "postgresql";
+ let graphDb = opts?.initial?.graphDb ?? "networkx";
+ let step = 0;
+
+ while (step < 3) {
+ if (step === 0) {
+ const picked = opts?.allowBack
+ ? await pickOne<"postgresql" | "milvus">({
+ message: "Vector database",
+ options: [
+ { value: "postgresql", label: "PostgreSQL + pgvector (default)", hint: "self-hosted, lightweight" },
+ { value: "milvus", label: "Milvus", hint: "dedicated vector DB" },
+ ],
+ initialValue: vectorDb,
+ allowBack: true,
+ backHint: opts.backHint,
+ })
+ : await pickOne<"postgresql" | "milvus">({
+ message: "Vector database",
+ options: [
+ { value: "postgresql", label: "PostgreSQL + pgvector (default)", hint: "self-hosted, lightweight" },
+ { value: "milvus", label: "Milvus", hint: "dedicated vector DB" },
+ ],
+ initialValue: vectorDb,
+ });
+ if (isPromptBack(picked)) return picked;
+ vectorDb = picked;
+ step = 1;
+ continue;
+ }
+ if (step === 1) {
+ const picked = await pickOne<"postgresql" | "mongo">({
+ message: "Data database (text chunks, observations, structured data)",
+ options: [
+ { value: "postgresql", label: "PostgreSQL (default)", hint: "reuses the same Postgres if picked above" },
+ { value: "mongo", label: "MongoDB" },
+ ],
+ initialValue: dataDb,
+ allowBack: true,
+ backHint: "Previous question",
+ });
+ if (isPromptBack(picked)) {
+ step = 0;
+ continue;
+ }
+ dataDb = picked;
+ step = 2;
+ continue;
+ }
+ const picked = await pickOne<"networkx" | "neo4j">({
+ message: "Graph database",
+ options: [
+ { value: "networkx", label: "NetworkX on PostgreSQL (default)", hint: "no extra DB server" },
+ { value: "neo4j", label: "Neo4j", hint: "dedicated graph DB" },
+ ],
+ initialValue: graphDb,
+ allowBack: true,
+ backHint: "Previous question",
+ });
+ if (isPromptBack(picked)) {
+ step = 1;
+ continue;
+ }
+ graphDb = picked;
+ return { vectorDb, dataDb, graphDb };
+ }
+
+ return { vectorDb, dataDb, graphDb };
+}
diff --git a/tui/src/flows/setup-wizard.ts b/tui/src/flows/setup-wizard.ts
new file mode 100644
index 0000000..b0b52f8
--- /dev/null
+++ b/tui/src/flows/setup-wizard.ts
@@ -0,0 +1,174 @@
+import * as p from "@clack/prompts";
+import { askUseDefaults, DEFAULT_DBS } from "./defaults.js";
+import { askDatabases } from "./services.js";
+import { askModels } from "./models.js";
+import { askPipeline } from "./pipeline.js";
+import { askConnections } from "./connections.js";
+import { askAuth } from "./auth.js";
+import { askServicesRuntime } from "./services-runtime.js";
+import { isPromptBack } from "../lib/prompts.js";
+import type {
+ AuthChoices,
+ Connections,
+ DbChoices,
+ InitChoices,
+ ModelsChoices,
+ PipelineChoices,
+ ServicesRuntime,
+} from "../types.js";
+
+export interface SetupDraft {
+ dbs?: DbChoices;
+ servicesRuntime?: ServicesRuntime;
+ models?: ModelsChoices;
+ pipeline?: PipelineChoices;
+ connections?: Connections;
+ auth?: AuthChoices;
+ usedDefaults?: boolean;
+}
+
+export interface RunSetupWizardOptions {
+ firstStepBack?: "return" | "cancel";
+ stepBackHint?: string;
+ firstStepBackHint?: string;
+}
+
+export function toInitChoices(draft: SetupDraft): InitChoices {
+ return {
+ dbs: draft.dbs!,
+ servicesRuntime: draft.servicesRuntime!,
+ models: draft.models!,
+ pipeline: draft.pipeline!,
+ connections: draft.connections!,
+ auth: draft.auth!,
+ usedDefaults: draft.usedDefaults ?? false,
+ };
+}
+
+export async function runSetupWizard(
+ draft: SetupDraft,
+ opts: RunSetupWizardOptions = {},
+): Promise<boolean> {
+ const stepBackHint = opts.stepBackHint ?? "Previous step";
+ const firstStepBackHint = opts.firstStepBackHint ?? stepBackHint;
+ let step = 0;
+
+ while (step >= 0) {
+ if (step === 0) {
+ const useDefaults = await askUseDefaults({
+ allowBack: true,
+ backHint: firstStepBackHint,
+ });
+ if (isPromptBack(useDefaults)) {
+ if (opts.firstStepBack === "cancel") {
+ p.cancel("Setup cancelled.");
+ process.exit(0);
+ }
+ return false;
+ }
+ draft.usedDefaults = useDefaults;
+ if (useDefaults) {
+ draft.dbs = DEFAULT_DBS;
+ draft.pipeline = { ocrMode: "docparser" };
+ step = 2;
+ continue;
+ }
+ step = 1;
+ continue;
+ }
+
+ if (step === 1) {
+ const dbs = await askDatabases({
+ allowBack: true,
+ backHint: stepBackHint,
+ initial: draft.dbs,
+ });
+ if (isPromptBack(dbs)) {
+ step = 0;
+ continue;
+ }
+ draft.dbs = dbs;
+ step = 2;
+ continue;
+ }
+
+ if (step === 2) {
+ if (!draft.dbs) {
+ step = 1;
+ continue;
+ }
+ const runtime = await askServicesRuntime(draft.dbs, {
+ allowBack: true,
+ backHint: stepBackHint,
+ initialValue: draft.servicesRuntime,
+ });
+ if (isPromptBack(runtime)) {
+ step = draft.usedDefaults ? 0 : 1;
+ continue;
+ }
+ draft.servicesRuntime = runtime;
+ step = 3;
+ continue;
+ }
+
+ if (step === 3) {
+ const models = draft.usedDefaults
+ ? await askModels({
+ prechosenMode: "remote",
+ initialMode: draft.models?.mode,
+ })
+ : await askModels({
+ allowBack: true,
+ backHint: stepBackHint,
+ initialMode: draft.models?.mode,
+ });
+ if (isPromptBack(models)) {
+ step = 2;
+ continue;
+ }
+ draft.models = models;
+ step = draft.usedDefaults ? 5 : 4;
+ continue;
+ }
+
+ if (step === 4) {
+ const pipeline = await askPipeline({
+ allowBack: true,
+ backHint: stepBackHint,
+ initialOcrMode: draft.pipeline?.ocrMode,
+ });
+ if (isPromptBack(pipeline)) {
+ step = 3;
+ continue;
+ }
+ draft.pipeline = pipeline;
+ step = 5;
+ continue;
+ }
+
+ if (step === 5) {
+ if (!draft.dbs) {
+ step = draft.usedDefaults ? 0 : 1;
+ continue;
+ }
+ draft.connections = await askConnections(draft.dbs);
+ step = 6;
+ continue;
+ }
+
+ if (step === 6) {
+ const auth = await askAuth({
+ allowBack: true,
+ backHint: stepBackHint,
+ });
+ if (isPromptBack(auth)) {
+ step = 5;
+ continue;
+ }
+ draft.auth = auth;
+ return true;
+ }
+ }
+
+ return false;
+}
diff --git a/tui/src/index.ts b/tui/src/index.ts
new file mode 100644
index 0000000..18d18e3
--- /dev/null
+++ b/tui/src/index.ts
@@ -0,0 +1,219 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { runInit } from "./commands/init.js";
+import { runStart } from "./commands/start.js";
+import { runConfig } from "./commands/config.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runUpdate } from "./commands/update.js";
+import { readState } from "./lib/state.js";
+import { isPipelineMode, type PipelineMode } from "./types.js";
+
+type Command = "init" | "start" | "config" | "doctor" | "update" | "help";
+
+interface ParsedArgs {
+ command: Command;
+ repo?: string;
+ branch?: string;
+ force?: boolean;
+ noApi?: boolean;
+ noMcp?: boolean;
+ noWorker?: boolean;
+ noServices?: boolean;
+ only?: Array<"api" | "mcp" | "worker" | "services">;
+ pipeline?: PipelineMode;
+ invalidPipeline?: string;
+ unknown: string[];
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+ const args = [...argv];
+ let command: Command = "help";
+ const unknown: string[] = [];
+ const out: ParsedArgs = { command, unknown };
+
+ while (args.length > 0) {
+ const arg = args.shift()!;
+ if (arg === "--repo" || arg === "-r") {
+ out.repo = args.shift();
+ } else if (arg === "--branch" || arg === "-b") {
+ out.branch = args.shift();
+ } else if (arg === "--force" || arg === "-f") {
+ out.force = true;
+ } else if (arg === "--no-api") {
+ out.noApi = true;
+ } else if (arg === "--no-mcp") {
+ out.noMcp = true;
+ } else if (arg === "--no-worker") {
+ out.noWorker = true;
+ } else if (arg === "--no-services") {
+ out.noServices = true;
+ } else if (arg === "--pipeline") {
+ const raw = (args.shift() ?? "").trim().toLowerCase();
+ if (isPipelineMode(raw)) {
+ out.pipeline = raw;
+ } else {
+ out.invalidPipeline = raw || "(missing)";
+ }
+ } else if (arg === "--only") {
+ const value = args.shift() ?? "";
+ const parts = value
+ .split(",")
+ .map((s) => s.trim().toLowerCase())
+ .filter((s) =>
+ s === "api" || s === "mcp" || s === "worker" || s === "services",
+ ) as Array<"api" | "mcp" | "worker" | "services">;
+ if (parts.length === 0) {
+ unknown.push(`--only ${value}`);
+ } else {
+ out.only = parts;
+ }
+ } else if (arg === "--help" || arg === "-h") {
+ out.command = "help";
+ } else if (arg === "--version" || arg === "-v") {
+ printVersion();
+ process.exit(0);
+ } else if (out.command === "help" && !arg.startsWith("-")) {
+ switch (arg) {
+ case "init":
+ case "start":
+ case "config":
+ case "doctor":
+ case "update":
+ case "help":
+ out.command = arg;
+ break;
+ default:
+ unknown.push(arg);
+ }
+ } else {
+ unknown.push(arg);
+ }
+ }
+ return out;
+}
+
+function printHelp(): void {
+ const lines = [
+ pc.bold("brainapi") + " — interactive installer for BrainAPI",
+ "",
+ pc.dim("Usage:") + " brainapi <command> [options]",
+ "",
+ pc.bold("Commands:"),
+ " init Clone repo, set up venv, run interactive config, optional containers",
+ " start [...] Start backing services + API + MCP + celery worker (Ctrl-C to stop all)",
+ " config Re-run the interactive flow and rewrite .env",
+ " doctor Check Python, Docker, Ollama, GCP credentials, services",
+ " update git pull + reinstall Python dependencies",
+ " help Show this message",
+ "",
+ pc.bold("Options:"),
+ " -r, --repo <url> Git repo to clone (default $BRAINAPI_REPO_URL or upstream)",
+ " -b, --branch <ref> Branch to checkout (default $BRAINAPI_BRANCH or 'main')",
+ " -f, --force Re-run init even if state exists",
+ " --no-services For 'start': skip bringing backing services up",
+ " --no-api For 'start': skip the API server",
+ " --no-mcp For 'start': skip the MCP server",
+ " --no-worker For 'start': skip the celery worker",
+ " --only api,mcp,worker For 'start': run only the listed processes (shortcut)",
+ " --pipeline accurate|lightweight Set PIPELINE_MODE in ~/.brainapi/source/.env before start",
+ " -v, --version Print the CLI version",
+ " -h, --help Show this message",
+ "",
+ pc.dim("Environment overrides: BRAINAPI_HOME, BRAINAPI_REPO_URL, BRAINAPI_BRANCH"),
+ ];
+ console.log(lines.join("\n"));
+}
+
+function printVersion(): void {
+ console.log("brainapi tui CLI");
+}
+
+async function autoInitIfNeeded(command: Command): Promise<Command> {
+ if (command === "help" || command === "init") return command;
+ const state = await readState();
+ if (state) return command;
+ p.log.info(
+ "No brainapi install found yet — running " + pc.cyan("brainapi init") + " first.",
+ );
+ return "init";
+}
+
+async function main(): Promise<void> {
+ const parsed = parseArgs(process.argv.slice(2));
+ if (parsed.invalidPipeline !== undefined) {
+ p.log.error(
+ `Invalid --pipeline value "${parsed.invalidPipeline}". Use accurate or lightweight.`,
+ );
+ process.exit(1);
+ }
+ if (parsed.unknown.length > 0 && parsed.command !== "help") {
+ p.log.warn("Unknown argument(s): " + parsed.unknown.join(", "));
+ }
+
+ let cmd = parsed.command;
+ if (cmd === "help") {
+ if (parsed.unknown.length === 0 && process.argv.slice(2).length === 0) {
+ cmd = await autoInitIfNeeded("init");
+ } else {
+ printHelp();
+ return;
+ }
+ } else {
+ cmd = await autoInitIfNeeded(cmd);
+ }
+
+ try {
+ switch (cmd) {
+ case "init":
+ await runInit({
+ repoUrl: parsed.repo,
+ branch: parsed.branch,
+ force: parsed.force,
+ });
+ return;
+ case "start": {
+ const startOpts = parsed.only
+ ? {
+ api: parsed.only.includes("api"),
+ mcp: parsed.only.includes("mcp"),
+ worker: parsed.only.includes("worker"),
+ services: parsed.only.includes("services") || true,
+ }
+ : {
+ api: !parsed.noApi,
+ mcp: !parsed.noMcp,
+ worker: !parsed.noWorker,
+ services: !parsed.noServices,
+ };
+ if (parsed.only) {
+ startOpts.services = parsed.only.includes("services");
+ }
+ await runStart({
+ ...startOpts,
+ pipelineMode: parsed.pipeline,
+ });
+ return;
+ }
+ case "config":
+ await runConfig();
+ return;
+ case "doctor":
+ await runDoctor();
+ return;
+ case "update":
+ await runUpdate();
+ return;
+ case "help":
+ printHelp();
+ return;
+ }
+ } catch (err) {
+ p.log.error(err instanceof Error ? err.message : String(err));
+ process.exit(1);
+ }
+}
+
+main().catch((err) => {
+ console.error(err);
+ process.exit(1);
+});
diff --git a/tui/src/lib/bring-up.ts b/tui/src/lib/bring-up.ts
new file mode 100644
index 0000000..c3769c3
--- /dev/null
+++ b/tui/src/lib/bring-up.ts
@@ -0,0 +1,165 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { composeFileExists, composeFileFor, composeUp } from "./docker.js";
+import { tcpProbe } from "./net.js";
+import { nativeRecipeFor } from "./native-install.js";
+import { detectCapabilities } from "./platform.js";
+import type { ServiceName } from "../constants.js";
+import type { ServiceTarget } from "./service-target.js";
+
+export interface BringUpInput {
+ service: ServiceName;
+ target: ServiceTarget | null;
+}
+
+export async function bringUpServices(items: BringUpInput[]): Promise<void> {
+ for (const { service, target } of items) {
+ if (target?.managed) {
+ p.log.info(
+ `${service}: managed deployment configured — skipping local docker compose up`,
+ );
+ continue;
+ }
+
+ if (!(await composeFileExists(service))) {
+ p.log.warn(
+ `${service}: compose file not found at ${pc.cyan(
+ composeFileFor(service),
+ )}. Skipping container start.`,
+ );
+ p.log.info(
+ `Fix: push ${pc.cyan(
+ `src/lib/${service}/docker-compose.yaml`,
+ )} to your remote, then re-run ${pc.cyan(
+ "brainapi update",
+ )}. Or copy it manually into ${pc.cyan("~/.brainapi/source/")}.`,
+ );
+ continue;
+ }
+
+ if (target && (await tcpProbe({ host: target.host, port: target.port, timeoutMs: 750 }))) {
+ p.log.info(
+ `${service} already reachable on ${target.host}:${target.port} — skipping ${pc.cyan(
+ "docker compose up",
+ )} (using existing service).`,
+ );
+ continue;
+ }
+
+ const spinner = p.spinner();
+ spinner.start(`docker compose up -d ${service}`);
+ try {
+ await composeUp(service);
+ spinner.stop(`${service} up`);
+ } catch (err) {
+ spinner.stop(pc.red(`${service} failed to start`));
+ p.log.error(err instanceof Error ? err.message : String(err));
+ }
+ }
+}
+
+const DEFAULT_WAIT_SECONDS = 60;
+const PROBE_INTERVAL_MS = 1500;
+
+export async function bringUpServicesManually(
+ items: BringUpInput[],
+): Promise<void> {
+ const caps = await detectCapabilities();
+
+ for (const { service, target } of items) {
+ if (target?.managed) {
+ p.log.info(
+ `${service}: managed deployment configured — using ${pc.cyan(
+ `${target.host}:${target.port}`,
+ )}`,
+ );
+ continue;
+ }
+
+ if (!target) {
+ p.log.warn(`${service}: no connection details configured. Skipping.`);
+ continue;
+ }
+
+ if (await tcpProbe({ host: target.host, port: target.port, timeoutMs: 750 })) {
+ p.log.success(
+ `${service} reachable on ${pc.cyan(`${target.host}:${target.port}`)}`,
+ );
+ continue;
+ }
+
+ p.log.warn(
+ `${service} is not running on ${pc.cyan(`${target.host}:${target.port}`)}.`,
+ );
+ printNativeRecipe(service, caps);
+
+ const ok = await waitForReachable(
+ service,
+ target.host,
+ target.port,
+ DEFAULT_WAIT_SECONDS,
+ );
+ if (!ok) {
+ p.log.warn(
+ `${service} still not reachable after ${DEFAULT_WAIT_SECONDS}s — continuing anyway. ` +
+ `BrainAPI will fail at runtime until you start ${pc.cyan(service)} on ${pc.cyan(
+ `${target.host}:${target.port}`,
+ )}.`,
+ );
+ }
+ }
+}
+
+function printNativeRecipe(
+ service: ServiceName,
+ caps: Awaited<ReturnType<typeof detectCapabilities>>,
+): void {
+ const recipe = nativeRecipeFor(service, caps);
+ if (!recipe) {
+ p.log.info(
+ `No native install recipe known for ${pc.cyan(
+ service,
+ )} on your platform. Please install it manually.`,
+ );
+ return;
+ }
+ if (recipe.unsupported) {
+ p.log.warn(`${service}: ${recipe.unsupported}`);
+ if (recipe.docsUrl) p.log.info(`Docs: ${pc.cyan(recipe.docsUrl)}`);
+ return;
+ }
+ const lines: string[] = [`Install ${pc.bold(service)}:`];
+ for (const cmd of recipe.install) lines.push(` ${pc.cyan(cmd)}`);
+ if (recipe.start.length > 0) {
+ lines.push("", "Start it:");
+ for (const cmd of recipe.start) lines.push(` ${pc.cyan(cmd)}`);
+ }
+ if (recipe.postInstall && recipe.postInstall.length > 0) {
+ lines.push("", "Post-install:");
+ for (const cmd of recipe.postInstall) lines.push(` ${pc.dim(cmd)}`);
+ }
+ if (recipe.docsUrl) {
+ lines.push("", `Docs: ${pc.cyan(recipe.docsUrl)}`);
+ }
+ p.note(lines.join("\n"), `${service} — manual install`);
+}
+
+async function waitForReachable(
+ service: ServiceName,
+ host: string,
+ port: number,
+ totalSeconds: number,
+): Promise<boolean> {
+ const spinner = p.spinner();
+ spinner.start(`Waiting for ${service} to become reachable on ${host}:${port}`);
+ const deadline = Date.now() + totalSeconds * 1000;
+ while (Date.now() < deadline) {
+ if (await tcpProbe({ host, port, timeoutMs: 750 })) {
+ spinner.stop(`${service} reachable on ${host}:${port}`);
+ return true;
+ }
+ await new Promise((resolve) => setTimeout(resolve, PROBE_INTERVAL_MS));
+ }
+ spinner.stop(pc.yellow(`${service} not reachable after ${totalSeconds}s`));
+ return false;
+}
diff --git a/tui/src/lib/docker-recovery.ts b/tui/src/lib/docker-recovery.ts
new file mode 100644
index 0000000..20bba3c
--- /dev/null
+++ b/tui/src/lib/docker-recovery.ts
@@ -0,0 +1,251 @@
+import { access } from "node:fs/promises";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { runInherit } from "./exec.js";
+import { detectDocker, waitForDaemon, type DockerState } from "./docker.js";
+import { detectCapabilities } from "./platform.js";
+import { askConfirm, pickOne } from "./prompts.js";
+
+interface DockerOption {
+ value: string;
+ label: string;
+ command?: { bin: string; args: string[] };
+ manualInstructions?: string;
+ openUrl?: string;
+}
+
+const MAX_RETRIES = 3;
+
+async function openUrl(url: string): Promise<void> {
+ const cmd = process.platform === "darwin"
+ ? { bin: "open", args: [url] }
+ : process.platform === "win32"
+ ? { bin: "cmd", args: ["/c", "start", "", url] }
+ : { bin: "xdg-open", args: [url] };
+ await runInherit(cmd.bin, cmd.args);
+}
+
+async function dockerDesktopExistsOnMac(): Promise<boolean> {
+ try {
+ await access("/Applications/Docker.app");
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function buildOptions(): Promise<DockerOption[]> {
+ const caps = await detectCapabilities();
+ const options: DockerOption[] = [];
+
+ if (caps.platform === "darwin") {
+ if (caps.hasBrew) {
+ options.push({
+ value: "brew-cask",
+ label: "Install Docker Desktop via Homebrew Cask (brew install --cask docker)",
+ command: { bin: "brew", args: ["install", "--cask", "docker"] },
+ });
+ }
+ options.push({
+ value: "docker-download-mac",
+ label: "Open Docker Desktop download page",
+ openUrl: "https://www.docker.com/products/docker-desktop/",
+ });
+ } else if (caps.platform === "linux") {
+ for (const pm of caps.linuxPackageManagers) {
+ const args = pm === "pacman"
+ ? ["sudo", pm, "-S", "--noconfirm", "docker", "docker-compose"]
+ : pm === "apk"
+ ? ["sudo", pm, "add", "docker", "docker-compose"]
+ : pm === "zypper"
+ ? ["sudo", pm, "install", "-y", "docker", "docker-compose"]
+ : ["sudo", pm, "install", "-y", "docker.io", "docker-compose-plugin"];
+ options.push({
+ value: `pm-${pm}`,
+ label: `Install via ${pm} (${args.slice(1).join(" ")})`,
+ command: { bin: args[0]!, args: args.slice(1) },
+ });
+ }
+ options.push({
+ value: "docker-script",
+ label: "Install via Docker's convenience script (curl -fsSL https://get.docker.com | sh)",
+ manualInstructions:
+ "curl -fsSL https://get.docker.com | sh\nsudo usermod -aG docker $USER\nnewgrp docker",
+ });
+ } else if (caps.platform === "win32") {
+ if (caps.hasWinget) {
+ options.push({
+ value: "winget",
+ label: "Install via winget (winget install Docker.DockerDesktop)",
+ command: { bin: "winget", args: ["install", "Docker.DockerDesktop"] },
+ });
+ }
+ if (caps.hasChoco) {
+ options.push({
+ value: "choco",
+ label: "Install via Chocolatey (choco install docker-desktop)",
+ command: { bin: "choco", args: ["install", "docker-desktop", "-y"] },
+ });
+ }
+ options.push({
+ value: "docker-download-win",
+ label: "Open Docker Desktop download page",
+ openUrl: "https://www.docker.com/products/docker-desktop/",
+ });
+ }
+
+ options.push({
+ value: "manual",
+ label: "I'll install it manually — wait and retry",
+ });
+ options.push({
+ value: "cancel",
+ label: "Cancel — skip container start",
+ });
+
+ return options;
+}
+
+function manualInstructionsFor(): string {
+ if (process.platform === "darwin") {
+ return [
+ "# Option A: Homebrew Cask",
+ "brew install --cask docker",
+ "",
+ "# Option B: Download installer",
+ "open https://www.docker.com/products/docker-desktop/",
+ ].join("\n");
+ }
+ if (process.platform === "linux") {
+ return [
+ "# Debian/Ubuntu",
+ "sudo apt-get install -y docker.io docker-compose-plugin",
+ "",
+ "# Fedora/RHEL",
+ "sudo dnf install -y docker docker-compose",
+ "",
+ "# Add yourself to the docker group:",
+ "sudo usermod -aG docker $USER",
+ "newgrp docker",
+ "",
+ "# Or convenience script:",
+ "curl -fsSL https://get.docker.com | sh",
+ ].join("\n");
+ }
+ return [
+ "winget install Docker.DockerDesktop",
+ "",
+ "# Or download:",
+ "https://www.docker.com/products/docker-desktop/",
+ ].join("\n");
+}
+
+async function handleMissing(): Promise<"installed" | "cancelled"> {
+ let attempt = 0;
+ while (attempt < MAX_RETRIES) {
+ attempt += 1;
+ p.log.warn(
+ attempt === 1
+ ? "Docker (or the compose plugin) was not found on your PATH."
+ : `Still no Docker detected (attempt ${attempt}/${MAX_RETRIES}).`,
+ );
+ const options = await buildOptions();
+ const choice = await pickOne<string>({
+ message: "How would you like to install Docker?",
+ options: options.map((o) => ({ value: o.value, label: o.label })),
+ });
+ if (choice === "cancel") return "cancelled";
+
+ const selected = options.find((o) => o.value === choice);
+ if (!selected) continue;
+
+ if (selected.openUrl) {
+ await openUrl(selected.openUrl);
+ } else if (selected.command) {
+ const cmdStr = `${selected.command.bin} ${selected.command.args.join(" ")}`;
+ p.note(cmdStr, "Command to run");
+ const confirmRun = await askConfirm({
+ message: "Run this for me now?",
+ initialValue: true,
+ });
+ if (confirmRun) {
+ await runInherit(selected.command.bin, selected.command.args);
+ }
+ } else if (selected.value === "manual") {
+ p.note(manualInstructionsFor(), "Manual install — copy and run");
+ } else if (selected.manualInstructions) {
+ p.note(selected.manualInstructions, "Copy and run");
+ }
+
+ await askConfirm({
+ message: "Press enter when Docker is installed",
+ initialValue: true,
+ });
+
+ const state = await detectDocker();
+ if (state === "ok") return "installed";
+ if (state === "daemon_down") {
+ const recovered = await handleDaemonDown();
+ if (recovered === "ok") return "installed";
+ if (recovered === "cancelled") return "cancelled";
+ }
+ }
+ return "cancelled";
+}
+
+async function handleDaemonDown(): Promise<"ok" | "cancelled"> {
+ p.log.warn("Docker is installed but the daemon is not responding.");
+
+ if (process.platform === "darwin" && (await dockerDesktopExistsOnMac())) {
+ const launch = await askConfirm({
+ message: "Launch Docker Desktop now?",
+ initialValue: true,
+ });
+ if (launch) {
+ await runInherit("open", ["-a", "Docker"]);
+ }
+ } else if (process.platform === "linux") {
+ p.note(
+ "sudo systemctl start docker",
+ "Try starting the daemon",
+ );
+ }
+
+ const spinner = p.spinner();
+ spinner.start("Waiting for Docker daemon (up to 60s)");
+ const ok = await waitForDaemon(60_000);
+ if (ok) {
+ spinner.stop(pc.green("Docker daemon is up."));
+ return "ok";
+ }
+ spinner.stop(pc.yellow("Docker daemon did not start in time."));
+ const retry = await askConfirm({
+ message: "Start Docker manually and press enter to retry — or cancel.",
+ initialValue: true,
+ });
+ if (!retry) return "cancelled";
+ const state = await detectDocker();
+ return state === "ok" ? "ok" : "cancelled";
+}
+
+export async function ensureDocker(): Promise<"ready" | "cancelled"> {
+ const state = await detectDocker();
+ if (state === "ok") return "ready";
+ if (state === "missing") {
+ const result = await handleMissing();
+ return result === "installed" ? "ready" : "cancelled";
+ }
+ const result = await handleDaemonDown();
+ return result === "ok" ? "ready" : "cancelled";
+}
+
+export function describeDockerState(state: DockerState): string {
+ switch (state) {
+ case "ok":
+ return "Docker is installed and the daemon is running";
+ case "missing":
+ return "Docker is not installed (or compose plugin missing)";
+ case "daemon_down":
+ return "Docker is installed but the daemon is not responding";
+ }
+}
diff --git a/tui/src/lib/docker.ts b/tui/src/lib/docker.ts
new file mode 100644
index 0000000..241e812
--- /dev/null
+++ b/tui/src/lib/docker.ts
@@ -0,0 +1,65 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { sourcePath } from "./paths.js";
+import { runInherit, runQuiet } from "./exec.js";
+import {
+ SERVICE_COMPOSE_FILES,
+ type ServiceName,
+} from "../constants.js";
+
+export type DockerState = "ok" | "missing" | "daemon_down";
+
+export async function detectDocker(): Promise<DockerState> {
+ const cli = await runQuiet("docker", ["--version"]);
+ if (!cli.ok) return "missing";
+ const compose = await runQuiet("docker", ["compose", "version"]);
+ if (!compose.ok) {
+ const legacy = await runQuiet("docker-compose", ["--version"]);
+ if (!legacy.ok) return "missing";
+ }
+ const info = await runQuiet("docker", ["info"]);
+ if (!info.ok) return "daemon_down";
+ return "ok";
+}
+
+export function composeFileFor(service: ServiceName): string {
+ return path.join(sourcePath(), SERVICE_COMPOSE_FILES[service]);
+}
+
+export async function composeFileExists(service: ServiceName): Promise<boolean> {
+ try {
+ await access(composeFileFor(service));
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export async function composeUp(service: ServiceName): Promise<void> {
+ const file = composeFileFor(service);
+ const result = await runInherit("docker", [
+ "compose",
+ "-f",
+ file,
+ "up",
+ "-d",
+ ]);
+ if (!result.ok) {
+ throw new Error(`docker compose up failed for ${service}`);
+ }
+}
+
+export async function composeDown(service: ServiceName): Promise<void> {
+ const file = composeFileFor(service);
+ await runInherit("docker", ["compose", "-f", file, "down"]);
+}
+
+export async function waitForDaemon(timeoutMs = 60_000): Promise<boolean> {
+ const start = Date.now();
+ while (Date.now() - start < timeoutMs) {
+ const info = await runQuiet("docker", ["info"]);
+ if (info.ok) return true;
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+ }
+ return false;
+}
diff --git a/tui/src/lib/env.ts b/tui/src/lib/env.ts
new file mode 100644
index 0000000..1666abb
--- /dev/null
+++ b/tui/src/lib/env.ts
@@ -0,0 +1,141 @@
+import { readFile, writeFile, access } from "node:fs/promises";
+import path from "node:path";
+import { ENV_KEYS } from "../constants.js";
+import type { PipelineMode } from "../types.js";
+import { envFilePath, sourcePath } from "./paths.js";
+
+const QUOTE_NEEDED = /[\s#"'=]/;
+
+function escapeValue(value: string): string {
+ if (value === "") return '""';
+ if (!QUOTE_NEEDED.test(value)) return value;
+ return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function parseLine(
+ line: string,
+): { key: string; rawValue: string } | null {
+ const trimmed = line.trim();
+ if (!trimmed || trimmed.startsWith("#")) return null;
+ const idx = line.indexOf("=");
+ if (idx < 0) return null;
+ return {
+ key: line.slice(0, idx).trim(),
+ rawValue: line.slice(idx + 1),
+ };
+}
+
+export interface EnvFile {
+ /** Original line content in file order. */
+ lines: string[];
+ /** Map of key -> index into `lines` for quick lookup/update. */
+ keyIndex: Map<string, number>;
+}
+
+export async function readEnvFile(filePath: string): Promise<EnvFile> {
+ let text = "";
+ try {
+ text = await readFile(filePath, "utf8");
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+ }
+ const lines = text.length === 0 ? [] : text.split(/\r?\n/);
+ if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+ const keyIndex = new Map<string, number>();
+ lines.forEach((line, i) => {
+ const parsed = parseLine(line);
+ if (parsed) keyIndex.set(parsed.key, i);
+ });
+ return { lines, keyIndex };
+}
+
+export function setEnvValue(env: EnvFile, key: string, value: string): void {
+ const newLine = `${key}=${escapeValue(value)}`;
+ const existing = env.keyIndex.get(key);
+ if (existing !== undefined) {
+ env.lines[existing] = newLine;
+ } else {
+ env.lines.push(newLine);
+ env.keyIndex.set(key, env.lines.length - 1);
+ }
+}
+
+export function removeEnvValue(env: EnvFile, key: string): void {
+ const existing = env.keyIndex.get(key);
+ if (existing === undefined) return;
+ env.lines.splice(existing, 1);
+ env.keyIndex.clear();
+ env.lines.forEach((line, i) => {
+ const parsed = parseLine(line);
+ if (parsed) env.keyIndex.set(parsed.key, i);
+ });
+}
+
+export function applyEnvValues(
+ env: EnvFile,
+ values: Record<string, string | number | undefined>,
+): void {
+ for (const [key, value] of Object.entries(values)) {
+ if (value === undefined) continue;
+ setEnvValue(env, key, String(value));
+ }
+}
+
+export async function writeEnvFile(
+ filePath: string,
+ env: EnvFile,
+): Promise<void> {
+ const content = env.lines.join("\n") + "\n";
+ await writeFile(filePath, content, "utf8");
+}
+
+export async function loadOrSeedEnv(): Promise<EnvFile> {
+ const targetPath = envFilePath();
+ try {
+ await access(targetPath);
+ return await readEnvFile(targetPath);
+ } catch {
+ const examplePath = path.join(sourcePath(), ".env.example");
+ return await readEnvFile(examplePath);
+ }
+}
+
+export async function saveEnv(env: EnvFile): Promise<void> {
+ await writeEnvFile(envFilePath(), env);
+}
+
+export async function setPipelineMode(mode: PipelineMode): Promise<void> {
+ const targetPath = envFilePath();
+ const env = await readEnvFile(targetPath);
+ setEnvValue(env, ENV_KEYS.pipelineMode, mode);
+ await writeEnvFile(targetPath, env);
+}
+
+export function getEnvValue(env: EnvFile, key: string): string | undefined {
+ const idx = env.keyIndex.get(key);
+ if (idx === undefined) return undefined;
+ const raw = (env.lines[idx] ?? "").split("=").slice(1).join("=");
+ return raw.trim().replace(/^"|"$/g, "");
+}
+
+export function resolvedModelsMode(env: EnvFile): "local" | "remote" {
+ const small = getEnvValue(env, "LLM_SMALL_PROVIDER");
+ const large = getEnvValue(env, "LLM_LARGE_PROVIDER");
+ const embeddings = getEnvValue(env, "EMBEDDINGS_PROVIDER");
+ if (small === "ollama" && large === "ollama" && embeddings === "ollama") {
+ return "local";
+ }
+ const mode = getEnvValue(env, "MODELS_MODE");
+ if (mode === "local" || mode === "remote") return mode;
+ return "remote";
+}
+
+export function envFileToProcessEnv(env: EnvFile): NodeJS.ProcessEnv {
+ const out: Record<string, string> = {};
+ for (const [key, idx] of env.keyIndex.entries()) {
+ const value = getEnvValue(env, key);
+ if (value !== undefined) out[key] = value;
+ }
+ out.MODELS_MODE = resolvedModelsMode(env);
+ return { ...process.env, ...out };
+}
diff --git a/tui/src/lib/exec.ts b/tui/src/lib/exec.ts
new file mode 100644
index 0000000..247c686
--- /dev/null
+++ b/tui/src/lib/exec.ts
@@ -0,0 +1,72 @@
+import { execa, type ExecaError, type Options } from "execa";
+
+export type RunResult = {
+ exitCode: number;
+ stdout: string;
+ stderr: string;
+ ok: boolean;
+};
+
+export async function runQuiet(
+ bin: string,
+ args: string[] = [],
+ options: Options = {},
+): Promise<RunResult> {
+ try {
+ const result = await execa(bin, args, {
+ reject: false,
+ stdout: "pipe",
+ stderr: "pipe",
+ ...options,
+ });
+ return {
+ exitCode: result.exitCode ?? 1,
+ stdout: result.stdout?.toString() ?? "",
+ stderr: result.stderr?.toString() ?? "",
+ ok: (result.exitCode ?? 1) === 0,
+ };
+ } catch (err) {
+ const ee = err as ExecaError;
+ return {
+ exitCode: typeof ee.exitCode === "number" ? ee.exitCode : 1,
+ stdout: ee.stdout?.toString() ?? "",
+ stderr: ee.stderr?.toString() ?? (ee.message ?? ""),
+ ok: false,
+ };
+ }
+}
+
+export async function runInherit(
+ bin: string,
+ args: string[] = [],
+ options: Options = {},
+): Promise<RunResult> {
+ try {
+ const result = await execa(bin, args, {
+ reject: false,
+ stdout: "inherit",
+ stderr: "inherit",
+ ...options,
+ });
+ return {
+ exitCode: result.exitCode ?? 1,
+ stdout: "",
+ stderr: "",
+ ok: (result.exitCode ?? 1) === 0,
+ };
+ } catch (err) {
+ const ee = err as ExecaError;
+ return {
+ exitCode: typeof ee.exitCode === "number" ? ee.exitCode : 1,
+ stdout: "",
+ stderr: ee.message ?? "",
+ ok: false,
+ };
+ }
+}
+
+export async function which(bin: string): Promise<boolean> {
+ const finder = process.platform === "win32" ? "where" : "which";
+ const result = await runQuiet(finder, [bin]);
+ return result.ok && result.stdout.trim().length > 0;
+}
diff --git a/tui/src/lib/git.ts b/tui/src/lib/git.ts
new file mode 100644
index 0000000..e378582
--- /dev/null
+++ b/tui/src/lib/git.ts
@@ -0,0 +1,53 @@
+import { access, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { simpleGit } from "simple-git";
+import { brainapiHome, sourcePath } from "./paths.js";
+import { updateState } from "./state.js";
+
+export interface CloneOptions {
+ repoUrl: string;
+ branch: string;
+ depth?: number;
+ onProgress?: (line: string) => void;
+}
+
+export async function isClonedRepo(): Promise<boolean> {
+ try {
+ await access(path.join(sourcePath(), ".git"));
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export async function cloneRepo(opts: CloneOptions): Promise<void> {
+ await mkdir(brainapiHome(), { recursive: true });
+ const target = sourcePath();
+ const git = simpleGit({
+ progress: ({ method, stage, progress }) => {
+ opts.onProgress?.(`${method} ${stage} ${progress}%`);
+ },
+ });
+ await git.clone(opts.repoUrl, target, [
+ "--branch",
+ opts.branch,
+ ...(opts.depth ? ["--depth", String(opts.depth)] : []),
+ ]);
+ await updateState({ cloned: true, repoUrl: opts.repoUrl, branch: opts.branch });
+}
+
+export async function pullRepo(branch: string): Promise<void> {
+ const git = simpleGit(sourcePath());
+ await git.fetch("origin", branch);
+ await git.checkout(branch);
+ await git.pull("origin", branch, { "--ff-only": null });
+}
+
+export async function ensureRepo(opts: CloneOptions): Promise<"cloned" | "pulled"> {
+ if (await isClonedRepo()) {
+ await pullRepo(opts.branch);
+ return "pulled";
+ }
+ await cloneRepo(opts);
+ return "cloned";
+}
diff --git a/tui/src/lib/native-install.ts b/tui/src/lib/native-install.ts
new file mode 100644
index 0000000..e70483e
--- /dev/null
+++ b/tui/src/lib/native-install.ts
@@ -0,0 +1,279 @@
+import type { ServiceName } from "../constants.js";
+import type { PlatformCapabilities, LinuxPackageManager } from "./platform.js";
+
+export interface NativeRecipe {
+ install: string[];
+ start: string[];
+ postInstall?: string[];
+ docsUrl?: string;
+ unsupported?: string;
+}
+
+function brewRecipe(service: ServiceName): NativeRecipe | undefined {
+ switch (service) {
+ case "redis":
+ return {
+ install: ["brew install redis"],
+ start: ["brew services start redis"],
+ docsUrl: "https://redis.io/docs/install/install-redis/install-redis-on-mac-os/",
+ };
+ case "postgresql":
+ return {
+ install: ["brew install postgresql@16", "brew install pgvector"],
+ start: ["brew services start postgresql@16"],
+ postInstall: [
+ "createdb \"$USER\" 2>/dev/null || true",
+ "psql -d postgres -c \"ALTER USER \\\"$USER\\\" WITH SUPERUSER;\"",
+ "echo \"Set POSTGRES_USERNAME / POSTGRES_PASSWORD in .env to match this role.\"",
+ ],
+ docsUrl: "https://github.com/pgvector/pgvector#installation",
+ };
+ case "neo4j":
+ return {
+ install: ["brew install neo4j"],
+ start: ["brew services start neo4j"],
+ postInstall: [
+ "# Default credentials are neo4j/neo4j — you'll be prompted to set a new password",
+ "# at first login: http://localhost:7474",
+ ],
+ docsUrl: "https://neo4j.com/docs/operations-manual/current/installation/osx/",
+ };
+ case "mongo":
+ return {
+ install: [
+ "brew tap mongodb/brew",
+ "brew install mongodb-community",
+ ],
+ start: ["brew services start mongodb/brew/mongodb-community"],
+ docsUrl: "https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-os-x/",
+ };
+ case "rabbitmq":
+ return {
+ install: ["brew install rabbitmq"],
+ start: ["brew services start rabbitmq"],
+ postInstall: [
+ "# Default guest user only works on localhost; the BrainAPI broker URL",
+ "# expects kalo/kalo — create it with:",
+ "rabbitmqctl add_user kalo kalo",
+ "rabbitmqctl set_user_tags kalo administrator",
+ "rabbitmqctl set_permissions -p / kalo \".*\" \".*\" \".*\"",
+ ],
+ docsUrl: "https://www.rabbitmq.com/install-homebrew.html",
+ };
+ case "milvus":
+ return undefined;
+ default:
+ return undefined;
+ }
+}
+
+function aptRecipe(service: ServiceName): NativeRecipe | undefined {
+ switch (service) {
+ case "redis":
+ return {
+ install: ["sudo apt-get update", "sudo apt-get install -y redis-server"],
+ start: ["sudo systemctl enable --now redis-server"],
+ };
+ case "postgresql":
+ return {
+ install: [
+ "sudo apt-get update",
+ "sudo apt-get install -y postgresql-16 postgresql-16-pgvector",
+ ],
+ start: ["sudo systemctl enable --now postgresql"],
+ postInstall: [
+ "sudo -u postgres createuser --superuser \"$USER\"",
+ "sudo -u postgres createdb \"$USER\"",
+ "# Then update POSTGRES_USERNAME / POSTGRES_PASSWORD in .env",
+ ],
+ docsUrl: "https://www.postgresql.org/download/linux/ubuntu/",
+ };
+ case "neo4j":
+ return {
+ install: [
+ "wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/neotechnology.gpg",
+ "echo 'deb [signed-by=/etc/apt/keyrings/neotechnology.gpg] https://debian.neo4j.com stable latest' | sudo tee /etc/apt/sources.list.d/neo4j.list",
+ "sudo apt-get update && sudo apt-get install -y neo4j",
+ ],
+ start: ["sudo systemctl enable --now neo4j"],
+ docsUrl: "https://neo4j.com/docs/operations-manual/current/installation/linux/debian/",
+ };
+ case "mongo":
+ return {
+ install: [
+ "curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor",
+ "echo 'deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse' | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list",
+ "sudo apt-get update && sudo apt-get install -y mongodb-org",
+ ],
+ start: ["sudo systemctl enable --now mongod"],
+ docsUrl: "https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/",
+ };
+ case "rabbitmq":
+ return {
+ install: ["sudo apt-get update", "sudo apt-get install -y rabbitmq-server"],
+ start: ["sudo systemctl enable --now rabbitmq-server"],
+ postInstall: [
+ "sudo rabbitmqctl add_user kalo kalo",
+ "sudo rabbitmqctl set_user_tags kalo administrator",
+ "sudo rabbitmqctl set_permissions -p / kalo \".*\" \".*\" \".*\"",
+ ],
+ };
+ case "milvus":
+ return undefined;
+ default:
+ return undefined;
+ }
+}
+
+function dnfRecipe(service: ServiceName): NativeRecipe | undefined {
+ switch (service) {
+ case "redis":
+ return {
+ install: ["sudo dnf install -y redis"],
+ start: ["sudo systemctl enable --now redis"],
+ };
+ case "postgresql":
+ return {
+ install: [
+ "sudo dnf install -y postgresql-server postgresql-contrib pgvector",
+ "sudo /usr/bin/postgresql-setup --initdb",
+ ],
+ start: ["sudo systemctl enable --now postgresql"],
+ docsUrl: "https://www.postgresql.org/download/linux/redhat/",
+ };
+ case "neo4j":
+ return {
+ install: [
+ "sudo rpm --import https://debian.neo4j.com/neotechnology.gpg.key",
+ "sudo dnf install -y neo4j",
+ ],
+ start: ["sudo systemctl enable --now neo4j"],
+ };
+ case "mongo":
+ return {
+ install: [
+ "# Add MongoDB official repo first — see docs",
+ "sudo dnf install -y mongodb-org",
+ ],
+ start: ["sudo systemctl enable --now mongod"],
+ docsUrl: "https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-red-hat/",
+ };
+ case "rabbitmq":
+ return {
+ install: ["sudo dnf install -y rabbitmq-server"],
+ start: ["sudo systemctl enable --now rabbitmq-server"],
+ postInstall: [
+ "sudo rabbitmqctl add_user kalo kalo",
+ "sudo rabbitmqctl set_user_tags kalo administrator",
+ "sudo rabbitmqctl set_permissions -p / kalo \".*\" \".*\" \".*\"",
+ ],
+ };
+ case "milvus":
+ return undefined;
+ default:
+ return undefined;
+ }
+}
+
+function genericLinuxRecipe(
+ service: ServiceName,
+ pm: LinuxPackageManager,
+): NativeRecipe | undefined {
+ if (pm === "apt-get") return aptRecipe(service);
+ if (pm === "dnf") return dnfRecipe(service);
+ if (pm === "pacman") {
+ switch (service) {
+ case "redis":
+ return {
+ install: ["sudo pacman -S --noconfirm redis"],
+ start: ["sudo systemctl enable --now redis"],
+ };
+ case "postgresql":
+ return {
+ install: [
+ "sudo pacman -S --noconfirm postgresql",
+ "# pgvector is available from the AUR: paru -S pgvector",
+ ],
+ start: [
+ "sudo -iu postgres initdb -D /var/lib/postgres/data",
+ "sudo systemctl enable --now postgresql",
+ ],
+ };
+ default:
+ return undefined;
+ }
+ }
+ return undefined;
+}
+
+function windowsRecipe(service: ServiceName): NativeRecipe | undefined {
+ switch (service) {
+ case "redis":
+ return {
+ install: [
+ "# Native Redis on Windows is no longer maintained.",
+ "# Use Memurai (commercial), WSL, or Docker instead.",
+ ],
+ start: [],
+ unsupported: "no first-party Windows build",
+ docsUrl: "https://www.memurai.com/get-memurai",
+ };
+ case "postgresql":
+ return {
+ install: ["winget install PostgreSQL.PostgreSQL"],
+ start: ["# postgresql-x64 service is auto-started by the installer"],
+ docsUrl: "https://www.postgresql.org/download/windows/",
+ };
+ case "neo4j":
+ return {
+ install: ["winget install Neo4j.Neo4jDesktop"],
+ start: [],
+ docsUrl: "https://neo4j.com/download/",
+ };
+ case "mongo":
+ return {
+ install: ["winget install MongoDB.Server"],
+ start: ["# MongoDB service is auto-started by the installer"],
+ };
+ case "rabbitmq":
+ return {
+ install: ["winget install RabbitMQ.RabbitMQ"],
+ start: ["# RabbitMQ service is auto-started by the installer"],
+ docsUrl: "https://www.rabbitmq.com/install-windows.html",
+ };
+ case "milvus":
+ return undefined;
+ default:
+ return undefined;
+ }
+}
+
+export function nativeRecipeFor(
+ service: ServiceName,
+ caps: PlatformCapabilities,
+): NativeRecipe | undefined {
+ if (service === "milvus") {
+ return {
+ install: [],
+ start: [],
+ unsupported:
+ "Milvus has no native install path — use Docker or Zilliz Cloud (managed).",
+ docsUrl: "https://milvus.io/docs/install_standalone-docker.md",
+ };
+ }
+ if (caps.platform === "darwin" && caps.hasBrew) {
+ const recipe = brewRecipe(service);
+ if (recipe) return recipe;
+ }
+ if (caps.platform === "linux") {
+ for (const pm of caps.linuxPackageManagers) {
+ const recipe = genericLinuxRecipe(service, pm);
+ if (recipe) return recipe;
+ }
+ }
+ if (caps.platform === "win32") {
+ const recipe = windowsRecipe(service);
+ if (recipe) return recipe;
+ }
+ return undefined;
+}
diff --git a/tui/src/lib/net.ts b/tui/src/lib/net.ts
new file mode 100644
index 0000000..ad7dd66
--- /dev/null
+++ b/tui/src/lib/net.ts
@@ -0,0 +1,55 @@
+import net from "node:net";
+
+export interface TcpProbeOptions {
+ host: string;
+ port: number;
+ timeoutMs?: number;
+}
+
+export async function tcpProbe({
+ host,
+ port,
+ timeoutMs = 1500,
+}: TcpProbeOptions): Promise<boolean> {
+ return new Promise<boolean>((resolve) => {
+ const socket = new net.Socket();
+ let settled = false;
+ const finish = (ok: boolean) => {
+ if (settled) return;
+ settled = true;
+ socket.destroy();
+ resolve(ok);
+ };
+ socket.setTimeout(timeoutMs);
+ socket.once("connect", () => finish(true));
+ socket.once("timeout", () => finish(false));
+ socket.once("error", () => finish(false));
+ socket.connect(port, host);
+ });
+}
+
+export interface HttpProbeOptions {
+ url: string;
+ timeoutMs?: number;
+ expectStatus?: number;
+}
+
+export async function httpProbe({
+ url,
+ timeoutMs = 2000,
+ expectStatus,
+}: HttpProbeOptions): Promise<{ ok: boolean; status?: number; body?: string }> {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
+ try {
+ const response = await fetch(url, { signal: controller.signal });
+ const body = await response.text();
+ const status = response.status;
+ const matches = expectStatus !== undefined ? status === expectStatus : status < 500;
+ return { ok: matches, status, body };
+ } catch {
+ return { ok: false };
+ } finally {
+ clearTimeout(timer);
+ }
+}
diff --git a/tui/src/lib/ollama.ts b/tui/src/lib/ollama.ts
new file mode 100644
index 0000000..3e82357
--- /dev/null
+++ b/tui/src/lib/ollama.ts
@@ -0,0 +1,67 @@
+import { httpProbe } from "./net.js";
+import { runInherit, which } from "./exec.js";
+
+export interface OllamaTarget {
+ host: string;
+ port: number;
+}
+
+export interface OllamaPullResult {
+ ok: boolean;
+ exitCode: number;
+ error?: string;
+}
+
+export async function pullOllamaModel(modelName: string): Promise<OllamaPullResult> {
+ const bin = (await which("ollama")) ? "ollama" : null;
+ if (!bin) {
+ return {
+ ok: false,
+ exitCode: 127,
+ error: "ollama CLI not found on PATH",
+ };
+ }
+ const result = await runInherit(bin, ["pull", modelName]);
+ if (result.ok) {
+ return { ok: true, exitCode: result.exitCode };
+ }
+ return {
+ ok: false,
+ exitCode: result.exitCode,
+ error: result.stderr || `ollama pull exited with code ${result.exitCode}`,
+ };
+}
+
+export async function isOllamaRunning(target: OllamaTarget): Promise<boolean> {
+ const result = await httpProbe({
+ url: `http://${target.host}:${target.port}/api/tags`,
+ expectStatus: 200,
+ });
+ return result.ok;
+}
+
+export async function listOllamaModels(target: OllamaTarget): Promise<string[]> {
+ const result = await httpProbe({
+ url: `http://${target.host}:${target.port}/api/tags`,
+ expectStatus: 200,
+ });
+ if (!result.ok || !result.body) return [];
+ try {
+ const json = JSON.parse(result.body) as { models?: Array<{ name?: string }> };
+ return (json.models ?? [])
+ .map((m) => m.name?.toString() ?? "")
+ .filter((name) => name.length > 0);
+ } catch {
+ return [];
+ }
+}
+
+export async function hasOllamaModel(
+ target: OllamaTarget,
+ modelName: string,
+): Promise<boolean> {
+ const models = await listOllamaModels(target);
+ if (models.includes(modelName)) return true;
+ const base = modelName.split(":")[0];
+ return base !== undefined && models.some((m) => m.split(":")[0] === base);
+}
diff --git a/tui/src/lib/parallel.ts b/tui/src/lib/parallel.ts
new file mode 100644
index 0000000..8b4bbc8
--- /dev/null
+++ b/tui/src/lib/parallel.ts
@@ -0,0 +1,103 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import pc from "picocolors";
+
+export interface ParallelJob {
+ name: string;
+ bin: string;
+ args: string[];
+ cwd?: string;
+ env?: NodeJS.ProcessEnv;
+ color?: (s: string) => string;
+}
+
+export interface ParallelResult {
+ name: string;
+ code: number | null;
+ signal: NodeJS.Signals | null;
+}
+
+const COLORS: Array<(s: string) => string> = [
+ pc.cyan,
+ pc.magenta,
+ pc.yellow,
+ pc.green,
+ pc.blue,
+ pc.red,
+];
+
+function makePrefixer(prefix: string): (chunk: Buffer | string) => string {
+ let pending = "";
+ return (chunk: Buffer | string): string => {
+ const text = pending + (typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+ const lines = text.split(/\r?\n/);
+ pending = lines.pop() ?? "";
+ if (lines.length === 0) return "";
+ return lines.map((line) => `${prefix} ${line}`).join("\n") + "\n";
+ };
+}
+
+export async function runParallel(jobs: ParallelJob[]): Promise<ParallelResult[]> {
+ if (jobs.length === 0) return [];
+
+ const labelWidth = Math.max(...jobs.map((j) => j.name.length));
+ const children: Array<{ name: string; child: ChildProcess }> = [];
+
+ const cleanup = (signal: NodeJS.Signals): void => {
+ for (const { child } of children) {
+ if (!child.killed) {
+ try {
+ child.kill(signal);
+ } catch {
+ }
+ }
+ }
+ };
+
+ const onSigint = (): void => cleanup("SIGINT");
+ const onSigterm = (): void => cleanup("SIGTERM");
+ process.on("SIGINT", onSigint);
+ process.on("SIGTERM", onSigterm);
+
+ try {
+ const results = await Promise.all(
+ jobs.map((job, idx) => {
+ const color = job.color ?? COLORS[idx % COLORS.length]!;
+ const label = job.name.padEnd(labelWidth);
+ const prefix = color(`[${label}]`);
+
+ const child = spawn(job.bin, job.args, {
+ cwd: job.cwd,
+ env: { ...process.env, ...job.env },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ children.push({ name: job.name, child });
+
+ const outPrefixer = makePrefixer(prefix);
+ const errPrefixer = makePrefixer(prefix);
+ child.stdout?.on("data", (chunk) => {
+ const out = outPrefixer(chunk);
+ if (out) process.stdout.write(out);
+ });
+ child.stderr?.on("data", (chunk) => {
+ const out = errPrefixer(chunk);
+ if (out) process.stderr.write(out);
+ });
+
+ return new Promise<ParallelResult>((resolve) => {
+ child.on("exit", (code, signal) => {
+ resolve({ name: job.name, code, signal });
+ });
+ child.on("error", (err) => {
+ process.stderr.write(`${prefix} failed to spawn: ${err.message}\n`);
+ resolve({ name: job.name, code: 127, signal: null });
+ });
+ });
+ }),
+ );
+
+ return results;
+ } finally {
+ process.off("SIGINT", onSigint);
+ process.off("SIGTERM", onSigterm);
+ }
+}
diff --git a/tui/src/lib/paths.ts b/tui/src/lib/paths.ts
new file mode 100644
index 0000000..c82b0b2
--- /dev/null
+++ b/tui/src/lib/paths.ts
@@ -0,0 +1,38 @@
+import { homedir, platform as osPlatform } from "node:os";
+import path from "node:path";
+import type { Platform } from "../types.js";
+
+export function brainapiHome(): string {
+ return process.env.BRAINAPI_HOME ?? path.join(homedir(), ".brainapi");
+}
+
+export function sourcePath(): string {
+ return path.join(brainapiHome(), "source");
+}
+
+export function venvPath(): string {
+ return path.join(sourcePath(), ".venv");
+}
+
+export function envFilePath(): string {
+ return path.join(sourcePath(), ".env");
+}
+
+export function stateFilePath(): string {
+ return path.join(brainapiHome(), "state.json");
+}
+
+export function venvBin(name: string): string {
+ if (currentPlatform() === "win32") {
+ return path.join(venvPath(), "Scripts", `${name}.exe`);
+ }
+ return path.join(venvPath(), "bin", name);
+}
+
+export function currentPlatform(): Platform {
+ const p = osPlatform();
+ if (p === "darwin" || p === "linux" || p === "win32") {
+ return p;
+ }
+ return "linux";
+}
diff --git a/tui/src/lib/platform.ts b/tui/src/lib/platform.ts
new file mode 100644
index 0000000..c82746e
--- /dev/null
+++ b/tui/src/lib/platform.ts
@@ -0,0 +1,46 @@
+import { currentPlatform } from "./paths.js";
+import { which } from "./exec.js";
+import type { Platform } from "../types.js";
+
+export type LinuxPackageManager = "apt-get" | "dnf" | "pacman" | "apk" | "zypper";
+
+export interface PlatformCapabilities {
+ platform: Platform;
+ hasBrew: boolean;
+ hasPyenv: boolean;
+ hasWinget: boolean;
+ hasChoco: boolean;
+ linuxPackageManagers: LinuxPackageManager[];
+}
+
+const LINUX_PMS: LinuxPackageManager[] = [
+ "apt-get",
+ "dnf",
+ "pacman",
+ "apk",
+ "zypper",
+];
+
+export async function detectCapabilities(): Promise<PlatformCapabilities> {
+ const platform = currentPlatform();
+ const [hasBrew, hasPyenv, hasWinget, hasChoco] = await Promise.all([
+ platform === "darwin" || platform === "linux" ? which("brew") : Promise.resolve(false),
+ which("pyenv"),
+ platform === "win32" ? which("winget") : Promise.resolve(false),
+ platform === "win32" ? which("choco") : Promise.resolve(false),
+ ]);
+ const linuxPackageManagers: LinuxPackageManager[] = [];
+ if (platform === "linux") {
+ for (const pm of LINUX_PMS) {
+ if (await which(pm)) linuxPackageManagers.push(pm);
+ }
+ }
+ return {
+ platform,
+ hasBrew,
+ hasPyenv,
+ hasWinget,
+ hasChoco,
+ linuxPackageManagers,
+ };
+}
diff --git a/tui/src/lib/prompts.ts b/tui/src/lib/prompts.ts
new file mode 100644
index 0000000..b791896
--- /dev/null
+++ b/tui/src/lib/prompts.ts
@@ -0,0 +1,127 @@
+import * as p from "@clack/prompts";
+
+export const PROMPT_BACK = "__back__" as const;
+export type PromptBack = typeof PROMPT_BACK;
+
+export function isPromptBack(value: unknown): value is PromptBack {
+ return value === PROMPT_BACK;
+}
+
+export interface PickOption<T extends string> {
+ value: T;
+ label: string;
+ hint?: string;
+}
+
+type PickOneBase<T extends string> = {
+ message: string;
+ options: PickOption<T>[];
+ initialValue?: T;
+};
+
+export async function pickOne<T extends string>(
+ opts: PickOneBase<T> & { allowBack?: false },
+): Promise<T>;
+export async function pickOne<T extends string>(
+ opts: PickOneBase<T> & {
+ allowBack: true;
+ backLabel?: string;
+ backHint?: string;
+ },
+): Promise<T | PromptBack>;
+export async function pickOne<T extends string>(
+ opts: PickOneBase<T> & {
+ allowBack?: boolean;
+ backLabel?: string;
+ backHint?: string;
+ },
+): Promise<T | PromptBack> {
+ const options = opts.allowBack
+ ? [
+ {
+ value: PROMPT_BACK as T,
+ label: opts.backLabel ?? "Back",
+ hint: opts.backHint,
+ },
+ ...opts.options,
+ ]
+ : opts.options;
+ const result = await (p.select as unknown as (o: {
+ message: string;
+ options: PickOption<T>[];
+ initialValue?: T;
+ }) => Promise<T | symbol>)({
+ message: opts.message,
+ options,
+ initialValue: opts.initialValue,
+ });
+ if (p.isCancel(result)) {
+ p.cancel("Setup cancelled.");
+ process.exit(1);
+ }
+ if (isPromptBack(result)) {
+ return PROMPT_BACK;
+ }
+ return result as T;
+}
+
+export async function askConfirmOrBack(opts: {
+ message: string;
+ initialValue?: boolean;
+ backHint?: string;
+}): Promise<boolean | PromptBack> {
+ const initial = opts.initialValue === false ? "no" : "yes";
+ const choice = await pickOne<"yes" | "no">({
+ message: opts.message,
+ allowBack: true,
+ backHint: opts.backHint,
+ initialValue: initial,
+ options: [
+ { value: "yes", label: "Yes" },
+ { value: "no", label: "No" },
+ ],
+ });
+ if (isPromptBack(choice)) {
+ return PROMPT_BACK;
+ }
+ return choice === "yes";
+}
+
+export async function askConfirm(opts: {
+ message: string;
+ initialValue?: boolean;
+}): Promise<boolean> {
+ const result = await p.confirm(opts);
+ if (p.isCancel(result)) {
+ p.cancel("Setup cancelled.");
+ process.exit(1);
+ }
+ return result as boolean;
+}
+
+export async function askText(opts: {
+ message: string;
+ placeholder?: string;
+ defaultValue?: string;
+ initialValue?: string;
+ validate?: (value: string) => string | undefined;
+}): Promise<string> {
+ const result = await p.text(opts);
+ if (p.isCancel(result)) {
+ p.cancel("Setup cancelled.");
+ process.exit(1);
+ }
+ return result as string;
+}
+
+export async function askPassword(opts: {
+ message: string;
+ validate?: (value: string) => string | undefined;
+}): Promise<string> {
+ const result = await p.password(opts);
+ if (p.isCancel(result)) {
+ p.cancel("Setup cancelled.");
+ process.exit(1);
+ }
+ return result as string;
+}
diff --git a/tui/src/lib/python-recovery.ts b/tui/src/lib/python-recovery.ts
new file mode 100644
index 0000000..a1dc268
--- /dev/null
+++ b/tui/src/lib/python-recovery.ts
@@ -0,0 +1,215 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { runInherit } from "./exec.js";
+import { detectCapabilities } from "./platform.js";
+import { detectPython, type DetectedPython } from "./python.js";
+import { askConfirm, pickOne } from "./prompts.js";
+
+interface PythonOption {
+ value: string;
+ label: string;
+ command?: { bin: string; args: string[] };
+ manualInstructions?: string;
+ openUrl?: string;
+}
+
+const MAX_RETRIES = 3;
+
+async function openUrl(url: string): Promise<void> {
+ const cmd = process.platform === "darwin"
+ ? { bin: "open", args: [url] }
+ : process.platform === "win32"
+ ? { bin: "cmd", args: ["/c", "start", "", url] }
+ : { bin: "xdg-open", args: [url] };
+ await runInherit(cmd.bin, cmd.args);
+}
+
+async function buildOptions(): Promise<PythonOption[]> {
+ const caps = await detectCapabilities();
+ const options: PythonOption[] = [];
+
+ if (caps.platform === "darwin") {
+ if (caps.hasBrew) {
+ options.push({
+ value: "brew",
+ label: "Install via Homebrew (brew install [email protected])",
+ command: { bin: "brew", args: ["install", "[email protected]"] },
+ });
+ }
+ options.push({
+ value: "pyenv-mac",
+ label: caps.hasPyenv
+ ? "Install via pyenv (pyenv install 3.12)"
+ : "Install pyenv + Python 3.12 (recommended for multiple versions)",
+ manualInstructions: caps.hasPyenv
+ ? "pyenv install 3.12.7\npyenv global 3.12.7"
+ : "brew install pyenv\npyenv install 3.12.7\npyenv global 3.12.7",
+ });
+ options.push({
+ value: "python-org-mac",
+ label: "Open python.org downloads in browser",
+ openUrl: "https://www.python.org/downloads/macos/",
+ });
+ } else if (caps.platform === "linux") {
+ for (const pm of caps.linuxPackageManagers) {
+ const installArgs = pm === "pacman"
+ ? ["sudo", pm, "-S", "--noconfirm", "python"]
+ : pm === "apk"
+ ? ["sudo", pm, "add", "python3", "py3-pip"]
+ : ["sudo", pm, "install", "-y", "python3.12", "python3.12-venv", "python3-pip"];
+ options.push({
+ value: `pm-${pm}`,
+ label: `Install via ${pm} (${installArgs.slice(1).join(" ")})`,
+ command: { bin: installArgs[0]!, args: installArgs.slice(1) },
+ });
+ }
+ if (caps.hasPyenv) {
+ options.push({
+ value: "pyenv-linux",
+ label: "Install via pyenv (pyenv install 3.12)",
+ manualInstructions: "pyenv install 3.12.7\npyenv global 3.12.7",
+ });
+ }
+ options.push({
+ value: "python-org-linux",
+ label: "Open python.org downloads in browser",
+ openUrl: "https://www.python.org/downloads/source/",
+ });
+ } else if (caps.platform === "win32") {
+ if (caps.hasWinget) {
+ options.push({
+ value: "winget",
+ label: "Install via winget (winget install Python.Python.3.12)",
+ command: { bin: "winget", args: ["install", "Python.Python.3.12"] },
+ });
+ }
+ if (caps.hasChoco) {
+ options.push({
+ value: "choco",
+ label: "Install via Chocolatey (choco install python --version=3.12)",
+ command: { bin: "choco", args: ["install", "python", "--version=3.12"] },
+ });
+ }
+ options.push({
+ value: "python-org-win",
+ label: "Open python.org downloads in browser",
+ openUrl: "https://www.python.org/downloads/windows/",
+ });
+ }
+
+ options.push({
+ value: "manual",
+ label: "I'll install it manually — wait and retry",
+ });
+ options.push({
+ value: "cancel",
+ label: "Cancel — I'll re-run `brainapi init` later",
+ });
+
+ return options;
+}
+
+function manualInstructionsFor(): string {
+ if (process.platform === "darwin") {
+ return [
+ "# Option A: Homebrew",
+ "brew install [email protected]",
+ "",
+ "# Option B: pyenv (recommended if you juggle Python versions)",
+ "brew install pyenv",
+ "pyenv install 3.12.7",
+ "pyenv global 3.12.7",
+ "",
+ "# Option C: Download installer",
+ "open https://www.python.org/downloads/macos/",
+ ].join("\n");
+ }
+ if (process.platform === "linux") {
+ return [
+ "# Debian/Ubuntu",
+ "sudo apt-get update && sudo apt-get install -y python3.12 python3.12-venv python3-pip",
+ "",
+ "# Fedora/RHEL",
+ "sudo dnf install -y python3.12",
+ "",
+ "# Arch",
+ "sudo pacman -S python",
+ "",
+ "# Or via pyenv",
+ "curl https://pyenv.run | bash",
+ "pyenv install 3.12.7 && pyenv global 3.12.7",
+ ].join("\n");
+ }
+ return [
+ "winget install Python.Python.3.12",
+ "",
+ "# Or download:",
+ "https://www.python.org/downloads/windows/",
+ ].join("\n");
+}
+
+export async function recoverPython(): Promise<DetectedPython> {
+ let attempt = 0;
+ while (attempt < MAX_RETRIES) {
+ attempt += 1;
+ p.log.warn(
+ attempt === 1
+ ? "Python 3.11+ was not found on your PATH."
+ : `Still no Python 3.11+ detected (attempt ${attempt}/${MAX_RETRIES}).`,
+ );
+ const options = await buildOptions();
+ const choice = await pickOne<string>({
+ message: "How would you like to install Python?",
+ options: options.map((o) => ({ value: o.value, label: o.label })),
+ });
+ const selected = options.find((o) => o.value === choice);
+ if (!selected) continue;
+
+ if (selected.value === "cancel") {
+ p.cancel("Setup cancelled. Re-run `brainapi init` once Python is installed.");
+ process.exit(1);
+ }
+
+ if (selected.openUrl) {
+ await openUrl(selected.openUrl);
+ } else if (selected.command) {
+ const cmdStr = `${selected.command.bin} ${selected.command.args.join(" ")}`;
+ p.note(cmdStr, "Command to run");
+ const confirmRun = await askConfirm({
+ message: "Run this for me now?",
+ initialValue: true,
+ });
+ if (confirmRun) {
+ await runInherit(selected.command.bin, selected.command.args);
+ }
+ } else if (selected.value === "manual") {
+ p.note(manualInstructionsFor(), "Manual install — copy and run");
+ } else if (selected.manualInstructions) {
+ p.note(selected.manualInstructions, "Copy and run");
+ }
+
+ await askConfirm({
+ message: "Press enter when Python is installed and on your PATH",
+ initialValue: true,
+ });
+
+ const detected = await detectPython();
+ if (detected) {
+ p.log.success(
+ `Found ${pc.cyan(detected.bin)} (Python ${detected.version.join(".")})`,
+ );
+ return detected;
+ }
+ }
+
+ p.cancel(
+ "Could not detect Python 3.11+ after several attempts. Open a fresh shell so PATH refreshes, then re-run `brainapi init`. Any cloned source is preserved.",
+ );
+ process.exit(1);
+}
+
+export async function ensurePython(): Promise<DetectedPython> {
+ const detected = await detectPython();
+ if (detected) return detected;
+ return recoverPython();
+}
diff --git a/tui/src/lib/python.ts b/tui/src/lib/python.ts
new file mode 100644
index 0000000..6e10046
--- /dev/null
+++ b/tui/src/lib/python.ts
@@ -0,0 +1,130 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+ MIN_PYTHON_VERSION,
+ PYTHON_CANDIDATES,
+} from "../constants.js";
+import { sourcePath, venvBin, venvPath } from "./paths.js";
+import { runQuiet, runInherit } from "./exec.js";
+import { updateState } from "./state.js";
+import { INSTALL_EXTRAS_SCRIPT as EMBEDDED_INSTALL_EXTRAS_SCRIPT } from "../embedded/install-extras-script.js";
+
+const INSTALL_EXTRAS_SCRIPT_REL = "scripts/install_extras.py";
+
+async function ensureInstallExtrasScript(): Promise<void> {
+ const target = path.join(sourcePath(), INSTALL_EXTRAS_SCRIPT_REL);
+ let existing: string | null = null;
+ try {
+ existing = await readFile(target, "utf8");
+ } catch {
+ existing = null;
+ }
+ if (existing === EMBEDDED_INSTALL_EXTRAS_SCRIPT) return;
+ await mkdir(path.dirname(target), { recursive: true });
+ await writeFile(target, EMBEDDED_INSTALL_EXTRAS_SCRIPT, "utf8");
+}
+
+export interface DetectedPython {
+ bin: string;
+ version: [number, number, number];
+}
+
+function meetsMinimum(version: [number, number, number]): boolean {
+ const [major, minor] = version;
+ const [minMajor, minMinor] = MIN_PYTHON_VERSION;
+ if (major > minMajor) return true;
+ if (major < minMajor) return false;
+ return minor >= minMinor;
+}
+
+export async function detectPython(): Promise<DetectedPython | null> {
+ for (const candidate of PYTHON_CANDIDATES) {
+ const result = await runQuiet(candidate, ["--version"]);
+ if (!result.ok) continue;
+ const output = result.stdout || result.stderr;
+ const match = output.match(/Python (\d+)\.(\d+)\.(\d+)/);
+ if (!match) continue;
+ const major = Number(match[1]);
+ const minor = Number(match[2]);
+ const patch = Number(match[3]);
+ const version: [number, number, number] = [major, minor, patch];
+ if (meetsMinimum(version)) {
+ return { bin: candidate, version };
+ }
+ }
+ return null;
+}
+
+export async function venvExists(): Promise<boolean> {
+ try {
+ await access(path.join(venvPath(), "pyvenv.cfg"));
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export async function createVenv(pythonBin: string): Promise<void> {
+ const result = await runInherit(pythonBin, ["-m", "venv", venvPath()]);
+ if (!result.ok) {
+ throw new Error(`python -m venv failed with exit code ${result.exitCode}`);
+ }
+ await updateState({ venvCreated: true });
+}
+
+export interface InstallDepsOptions {
+ extras?: string[];
+ skipBase?: boolean;
+}
+
+function scriptArgs(opts: InstallDepsOptions, withUpgrade: boolean): string[] {
+ const args: string[] = [INSTALL_EXTRAS_SCRIPT_REL];
+ if (!opts.skipBase) args.push("--include-base");
+ if (withUpgrade) args.push("--upgrade-pip");
+ for (const extra of opts.extras ?? []) {
+ args.push(extra);
+ }
+ return args;
+}
+
+export async function installDeps(options: InstallDepsOptions = {}): Promise<void> {
+ await ensureInstallExtrasScript();
+ const pythonBin = venvBin("python");
+ const args = scriptArgs(options, true);
+ const result = await runInherit(pythonBin, args, { cwd: sourcePath() });
+ if (!result.ok) {
+ throw new Error(`scripts/install_extras.py failed with exit code ${result.exitCode}`);
+ }
+ if (!options.skipBase) {
+ await updateState({ depsInstalled: true });
+ }
+}
+
+export async function installExtras(extras: string[]): Promise<void> {
+ if (extras.length === 0) return;
+ await installDeps({ extras, skipBase: true });
+}
+
+export async function missingExtras(extras: string[]): Promise<string[]> {
+ if (extras.length === 0) return [];
+ await ensureInstallExtrasScript();
+ const pythonBin = venvBin("python");
+ const result = await runQuiet(
+ pythonBin,
+ [INSTALL_EXTRAS_SCRIPT_REL, "--check", ...extras],
+ { cwd: sourcePath() },
+ );
+ if (result.ok) return [];
+ return [...extras];
+}
+
+export async function missingRequiredPythonDeps(): Promise<boolean> {
+ await ensureInstallExtrasScript();
+ const pythonBin = venvBin("python");
+ const result = await runQuiet(
+ pythonBin,
+ [INSTALL_EXTRAS_SCRIPT_REL, "--check"],
+ { cwd: sourcePath() },
+ );
+ return !result.ok;
+}
diff --git a/tui/src/lib/service-target.ts b/tui/src/lib/service-target.ts
new file mode 100644
index 0000000..872de1b
--- /dev/null
+++ b/tui/src/lib/service-target.ts
@@ -0,0 +1,110 @@
+import type { Connections } from "../types.js";
+import type { ServiceName } from "../constants.js";
+import { SERVICE_DEFAULTS } from "../constants.js";
+
+export interface ServiceTarget {
+ host: string;
+ port: number;
+ managed?: boolean;
+}
+
+export function targetFromConnections(
+ service: ServiceName,
+ connections: Connections,
+): ServiceTarget | null {
+ switch (service) {
+ case "redis":
+ return {
+ host: connections.redis.host,
+ port: connections.redis.port,
+ };
+ case "postgresql":
+ if (!connections.postgresql) return null;
+ return {
+ host: connections.postgresql.host,
+ port: connections.postgresql.port,
+ };
+ case "neo4j":
+ if (!connections.neo4j) return null;
+ return {
+ host: connections.neo4j.host,
+ port: connections.neo4j.port,
+ };
+ case "milvus":
+ if (!connections.milvus) return null;
+ if (connections.milvus.uri) {
+ return {
+ host: connections.milvus.host,
+ port: connections.milvus.port,
+ managed: true,
+ };
+ }
+ return {
+ host: connections.milvus.host,
+ port: connections.milvus.port,
+ };
+ case "mongo":
+ if (!connections.mongo) return null;
+ return {
+ host: connections.mongo.host,
+ port: connections.mongo.port,
+ };
+ case "rabbitmq":
+ return {
+ host: SERVICE_DEFAULTS.rabbitmq.host,
+ port: SERVICE_DEFAULTS.rabbitmq.port,
+ };
+ default:
+ return null;
+ }
+}
+
+export function targetFromEnv(
+ service: ServiceName,
+ getter: (key: string) => string | undefined,
+): ServiceTarget | null {
+ const defaults = SERVICE_DEFAULTS;
+ switch (service) {
+ case "redis":
+ return {
+ host: getter("REDIS_HOST") ?? defaults.redis.host,
+ port: Number(getter("REDIS_PORT") ?? defaults.redis.port),
+ };
+ case "postgresql":
+ return {
+ host: getter("POSTGRES_HOST") ?? defaults.postgresql.host,
+ port: Number(getter("POSTGRES_PORT") ?? defaults.postgresql.port),
+ };
+ case "neo4j":
+ return {
+ host: getter("NEO4J_HOST") ?? defaults.neo4j.host,
+ port: Number(getter("NEO4J_PORT") ?? defaults.neo4j.port),
+ };
+ case "milvus": {
+ const uri = getter("MILVUS_URI");
+ if (uri && uri.length > 0) {
+ return {
+ host: getter("MILVUS_HOST") ?? defaults.milvus.host,
+ port: Number(getter("MILVUS_PORT") ?? defaults.milvus.port),
+ managed: true,
+ };
+ }
+ return {
+ host: getter("MILVUS_HOST") ?? defaults.milvus.host,
+ port: Number(getter("MILVUS_PORT") ?? defaults.milvus.port),
+ };
+ }
+ case "mongo":
+ return {
+ host: getter("MONGO_HOST") ?? defaults.mongo.host,
+ port: Number(getter("MONGO_PORT") ?? defaults.mongo.port),
+ };
+ case "rabbitmq":
+ return {
+ host: getter("RABBITMQ_HOST") ?? defaults.rabbitmq.host,
+ port: Number(getter("RABBITMQ_PORT") ?? defaults.rabbitmq.port),
+ };
+ default:
+ return null;
+ }
+}
diff --git a/tui/src/lib/state.ts b/tui/src/lib/state.ts
new file mode 100644
index 0000000..fd7e4bf
--- /dev/null
+++ b/tui/src/lib/state.ts
@@ -0,0 +1,49 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { brainapiHome, sourcePath, stateFilePath } from "./paths.js";
+import { DEFAULT_BRANCH, DEFAULT_REPO_URL } from "../constants.js";
+import type { InstallState } from "../types.js";
+
+export function defaultState(): InstallState {
+ return {
+ cloned: false,
+ venvCreated: false,
+ depsInstalled: false,
+ envWritten: false,
+ containersStarted: false,
+ selectedServices: null,
+ servicesRuntime: null,
+ sourcePath: sourcePath(),
+ repoUrl: process.env.BRAINAPI_REPO_URL ?? DEFAULT_REPO_URL,
+ branch: process.env.BRAINAPI_BRANCH ?? DEFAULT_BRANCH,
+ };
+}
+
+export async function readState(): Promise<InstallState | null> {
+ try {
+ const raw = await readFile(stateFilePath(), "utf8");
+ const parsed = JSON.parse(raw) as Partial<InstallState>;
+ return { ...defaultState(), ...parsed };
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+ throw err;
+ }
+}
+
+export async function writeState(state: InstallState): Promise<void> {
+ await mkdir(path.dirname(stateFilePath()), { recursive: true });
+ await writeFile(stateFilePath(), JSON.stringify(state, null, 2), "utf8");
+}
+
+export async function updateState(
+ patch: Partial<InstallState>,
+): Promise<InstallState> {
+ const current = (await readState()) ?? defaultState();
+ const next = { ...current, ...patch };
+ await writeState(next);
+ return next;
+}
+
+export async function ensureStateDir(): Promise<void> {
+ await mkdir(brainapiHome(), { recursive: true });
+}
diff --git a/tui/src/lib/sync-source.ts b/tui/src/lib/sync-source.ts
new file mode 100644
index 0000000..9309a19
--- /dev/null
+++ b/tui/src/lib/sync-source.ts
@@ -0,0 +1,58 @@
+import { access, cp } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { sourcePath } from "./paths.js";
+
+const SYNC_PATHS = [
+ "src/config.py",
+ "src/core/instances.py",
+ "src/lib/llm",
+ "src/lib/embeddings",
+ "src/lib/postgresql",
+] as const;
+
+async function pathExists(target: string): Promise<boolean> {
+ try {
+ await access(target);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export async function devWorkspaceRoot(): Promise<string | null> {
+ const fromEnv = process.env.BRAINAPI_DEV_SOURCE?.trim();
+ if (fromEnv && (await pathExists(path.join(fromEnv, "src", "config.py")))) {
+ return fromEnv;
+ }
+
+ const distDir = path.dirname(fileURLToPath(import.meta.url));
+ const candidate = path.resolve(distDir, "..", "..", "..");
+ if (await pathExists(path.join(candidate, "src", "config.py"))) {
+ return candidate;
+ }
+ return null;
+}
+
+export async function syncDevSourceIfAvailable(): Promise<boolean> {
+ const root = await devWorkspaceRoot();
+ if (!root) return false;
+
+ const destRoot = sourcePath();
+ let synced = false;
+ for (const rel of SYNC_PATHS) {
+ const src = path.join(root, rel);
+ const dest = path.join(destRoot, rel);
+ if (!(await pathExists(src))) continue;
+ await cp(src, dest, { recursive: true, force: true });
+ synced = true;
+ }
+ if (synced) {
+ p.log.info(
+ `Synced Python sources from ${pc.cyan(root)} → ${pc.cyan(destRoot)}`,
+ );
+ }
+ return synced;
+}
diff --git a/tui/src/lib/write-env.ts b/tui/src/lib/write-env.ts
new file mode 100644
index 0000000..fdcf0db
--- /dev/null
+++ b/tui/src/lib/write-env.ts
@@ -0,0 +1,276 @@
+import {
+ AZURE_DEFAULT_EMBEDDING_MODEL,
+ AZURE_DEFAULT_LARGE_API_VERSION,
+ AZURE_DEFAULT_LARGE_MODEL,
+ AZURE_DEFAULT_SMALL_MODEL,
+ BEDROCK_DEFAULT_EMBEDDING_MODEL,
+ BEDROCK_DEFAULT_LARGE_MODEL,
+ BEDROCK_DEFAULT_REGION,
+ BEDROCK_DEFAULT_SMALL_MODEL,
+ EMBEDDINGS_DEFAULTS,
+ OPENAI_DEFAULT_EMBEDDING_MODEL,
+ OPENAI_DEFAULT_LARGE_MODEL,
+ OPENAI_DEFAULT_SMALL_MODEL,
+ OLLAMA_EMBEDDING_DIMENSIONS,
+ ENV_KEYS,
+ GCP_DEFAULT_EMBEDDING_MODEL,
+ GCP_DEFAULT_LARGE_MODEL,
+ GCP_DEFAULT_SMALL_MODEL,
+ OLLAMA_DEFAULT_HOST,
+ OLLAMA_DEFAULT_LARGE_MODEL,
+ OLLAMA_DEFAULT_PORT,
+ OLLAMA_DEFAULT_SMALL_MODEL,
+ SERVICE_DEFAULTS,
+} from "../constants.js";
+import { applyEnvValues, loadOrSeedEnv, removeEnvValue, saveEnv } from "./env.js";
+import type { InitChoices } from "../types.js";
+import { resolveActiveEmbeddingModel } from "../flows/embedding-dimensions.js";
+import { lookupEmbeddingDimensions } from "../constants.js";
+
+const AZURE_ENDPOINT_PLACEHOLDER = "https://example.openai.azure.com";
+const AZURE_EMBEDDING_PLACEHOLDER =
+ "https://example.openai.azure.com/openai/deployments/text-embedding-3-large/embeddings?api-version=2023-05-15";
+const AZURE_KEY_PLACEHOLDER = "azure-key-placeholder";
+const OPENAI_KEY_PLACEHOLDER = "openai-api-key-placeholder";
+
+function resolveModelsMode(choices: InitChoices): "local" | "remote" {
+ const { llmSmallProvider, llmLargeProvider, embeddingsProvider } = choices.models;
+ if (
+ llmSmallProvider === "ollama" &&
+ llmLargeProvider === "ollama" &&
+ embeddingsProvider === "ollama"
+ ) {
+ return "local";
+ }
+ return choices.models.mode;
+}
+
+export async function writeEnvFromChoices(choices: InitChoices): Promise<void> {
+ const env = await loadOrSeedEnv();
+ const values: Record<string, string | number | undefined> = {};
+
+ values[ENV_KEYS.graphDb] = choices.dbs.graphDb;
+ values[ENV_KEYS.dataDb] = choices.dbs.dataDb;
+ values[ENV_KEYS.vectorDb] = choices.dbs.vectorDb;
+ values[ENV_KEYS.modelsMode] = resolveModelsMode(choices);
+ values[ENV_KEYS.ocrMode] = choices.pipeline.ocrMode;
+ values[ENV_KEYS.pipelineMode] = "accurate";
+ values[ENV_KEYS.agenticArchitecture] = "custom";
+ values[ENV_KEYS.runGraphConsolidator] = "true";
+ values[ENV_KEYS.celeryWorkerConcurrency] = 4;
+
+ values[ENV_KEYS.brainpatToken] = choices.auth.brainpatToken;
+
+ values[ENV_KEYS.redisHost] = choices.connections.redis.host;
+ values[ENV_KEYS.redisPort] = choices.connections.redis.port;
+
+ applyPostgresValues(values, choices);
+ applyNeo4jValues(values, choices);
+ applyMilvusValues(values, choices, env);
+ applyMongoValues(values, choices);
+ applyOllamaValues(values, choices);
+ applyRemoteModelValues(values, choices);
+ applyEmbeddingDefaults(values, choices);
+
+ applyEnvValues(env, values);
+ await saveEnv(env);
+}
+
+function applyPostgresValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ const pg = choices.connections.postgresql;
+ const defaults = SERVICE_DEFAULTS.postgresql;
+ values[ENV_KEYS.postgresHost] = pg?.host ?? defaults.host;
+ values[ENV_KEYS.postgresPort] = pg?.port ?? defaults.port;
+ values[ENV_KEYS.postgresUsername] = pg?.username ?? defaults.username;
+ values[ENV_KEYS.postgresPassword] = pg?.password ?? defaults.password;
+ values[ENV_KEYS.postgresSystemDatabase] =
+ pg?.systemDatabase ?? defaults.systemDatabase;
+ values[ENV_KEYS.postgresMaintenanceDatabase] =
+ pg?.maintenanceDatabase ?? defaults.maintenanceDatabase;
+}
+
+function applyNeo4jValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ const neo = choices.connections.neo4j;
+ const defaults = SERVICE_DEFAULTS.neo4j;
+ values[ENV_KEYS.neo4jHost] = neo?.host ?? defaults.host;
+ values[ENV_KEYS.neo4jPort] = neo?.port ?? defaults.port;
+ values[ENV_KEYS.neo4jUsername] = neo?.username ?? defaults.username;
+ values[ENV_KEYS.neo4jPassword] = neo?.password ?? defaults.password;
+}
+
+function applyMilvusValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+ env: Awaited<ReturnType<typeof loadOrSeedEnv>>,
+): void {
+ const mv = choices.connections.milvus;
+ const defaults = SERVICE_DEFAULTS.milvus;
+ values[ENV_KEYS.milvusHost] = mv?.host ?? defaults.host;
+ values[ENV_KEYS.milvusPort] = mv?.port ?? defaults.port;
+ if (mv?.uri) {
+ values[ENV_KEYS.milvusUri] = mv.uri;
+ } else {
+ removeEnvValue(env, ENV_KEYS.milvusUri);
+ }
+ if (mv?.token) {
+ values[ENV_KEYS.milvusToken] = mv.token;
+ } else {
+ removeEnvValue(env, ENV_KEYS.milvusToken);
+ }
+}
+
+function applyMongoValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ const mg = choices.connections.mongo;
+ const defaults = SERVICE_DEFAULTS.mongo;
+ values[ENV_KEYS.mongoHost] = mg?.host ?? defaults.host;
+ values[ENV_KEYS.mongoPort] = mg?.port ?? defaults.port;
+ values[ENV_KEYS.mongoUsername] = mg?.username ?? defaults.username;
+ values[ENV_KEYS.mongoPassword] = mg?.password ?? defaults.password;
+ values[ENV_KEYS.mongoSystemDatabase] = "system";
+}
+
+function applyOllamaValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ const usesOllama =
+ choices.models.llmSmallProvider === "ollama" ||
+ choices.models.llmLargeProvider === "ollama" ||
+ choices.models.embeddingsProvider === "ollama";
+ if (usesOllama && choices.models.ollama) {
+ const ol = choices.models.ollama;
+ values[ENV_KEYS.ollamaHost] = ol.host;
+ values[ENV_KEYS.ollamaPort] = ol.port;
+ values[ENV_KEYS.ollamaSmallModel] = ol.smallModel;
+ values[ENV_KEYS.ollamaLargeModel] = ol.largeModel;
+ values[ENV_KEYS.embeddingsLocalModel] = ol.embeddingsLocalModel;
+ return;
+ }
+ values[ENV_KEYS.ollamaHost] = OLLAMA_DEFAULT_HOST;
+ values[ENV_KEYS.ollamaPort] = OLLAMA_DEFAULT_PORT;
+ values[ENV_KEYS.ollamaSmallModel] = OLLAMA_DEFAULT_SMALL_MODEL;
+ values[ENV_KEYS.ollamaLargeModel] = OLLAMA_DEFAULT_LARGE_MODEL;
+}
+
+function applyRemoteModelValues(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ const gcp = choices.models.gcp;
+ const azure = choices.models.azure;
+ const openai = choices.models.openai;
+ const bedrock = choices.models.bedrock;
+ values[ENV_KEYS.llmSmallProvider] = choices.models.llmSmallProvider;
+ values[ENV_KEYS.llmLargeProvider] = choices.models.llmLargeProvider;
+ values[ENV_KEYS.embeddingsProvider] = choices.models.embeddingsProvider;
+ values[ENV_KEYS.gcpCredentialsPath] = gcp?.credentialsPath ?? "gcp_credentials.json";
+ values[ENV_KEYS.gcpProjectId] = gcp?.projectId ?? "your-project-id";
+ values[ENV_KEYS.gcpSmallLlmModel] = gcp?.smallLlmModel ?? GCP_DEFAULT_SMALL_MODEL;
+ values[ENV_KEYS.gcpExtraSmallLlmModel] =
+ gcp?.smallLlmModel ?? GCP_DEFAULT_SMALL_MODEL;
+ values[ENV_KEYS.gcpLargeLlmModel] = gcp?.largeLlmModel ?? GCP_DEFAULT_LARGE_MODEL;
+ values[ENV_KEYS.gcpEmbeddingModel] = gcp?.embeddingModel ?? GCP_DEFAULT_EMBEDDING_MODEL;
+
+ values[ENV_KEYS.azureSmallLlmModel] =
+ azure?.smallLlmModel ?? AZURE_DEFAULT_SMALL_MODEL;
+ values[ENV_KEYS.azureLargeLlmModel] =
+ azure?.largeLlmModel ?? AZURE_DEFAULT_LARGE_MODEL;
+ values[ENV_KEYS.azureLlmApiVersion] =
+ azure?.llmApiVersion ?? AZURE_DEFAULT_LARGE_API_VERSION;
+ values[ENV_KEYS.azureLlmEndpoint] =
+ azure?.llmEndpoint ?? AZURE_ENDPOINT_PLACEHOLDER;
+ values[ENV_KEYS.azureLlmSubscriptionKey] =
+ azure?.llmSubscriptionKey ?? AZURE_KEY_PLACEHOLDER;
+ values[ENV_KEYS.azureLargeLlmApiVersion] =
+ azure?.llmApiVersion ?? AZURE_DEFAULT_LARGE_API_VERSION;
+ values[ENV_KEYS.azureLargeLlmEndpoint] =
+ azure?.llmEndpoint ?? AZURE_ENDPOINT_PLACEHOLDER;
+ values[ENV_KEYS.azureLargeLlmSubscriptionKey] =
+ azure?.llmSubscriptionKey ?? AZURE_KEY_PLACEHOLDER;
+ values[ENV_KEYS.azureEmbeddingModel] =
+ azure?.embeddingModel ?? AZURE_DEFAULT_EMBEDDING_MODEL;
+ values[ENV_KEYS.azureEmbeddingFullEndpoint] =
+ azure?.embeddingEndpoint ?? AZURE_EMBEDDING_PLACEHOLDER;
+ values[ENV_KEYS.azureEmbeddingKey] =
+ azure?.embeddingKey ?? AZURE_KEY_PLACEHOLDER;
+
+ values[ENV_KEYS.openaiApiKey] = openai?.apiKey ?? OPENAI_KEY_PLACEHOLDER;
+ values[ENV_KEYS.openaiSmallLlmModel] =
+ openai?.smallLlmModel ?? OPENAI_DEFAULT_SMALL_MODEL;
+ values[ENV_KEYS.openaiLargeLlmModel] =
+ openai?.largeLlmModel ?? OPENAI_DEFAULT_LARGE_MODEL;
+ values[ENV_KEYS.openaiEmbeddingModel] =
+ openai?.embeddingModel ?? OPENAI_DEFAULT_EMBEDDING_MODEL;
+ if (openai?.baseUrl) {
+ values[ENV_KEYS.openaiBaseUrl] = openai.baseUrl;
+ } else {
+ values[ENV_KEYS.openaiBaseUrl] = "";
+ }
+ values[ENV_KEYS.bedrockAccessKeyId] = bedrock?.accessKeyId ?? "your-access-key-id";
+ values[ENV_KEYS.bedrockSecretAccessKey] =
+ bedrock?.secretAccessKey ?? "your-secret-access-key";
+ values[ENV_KEYS.bedrockSessionToken] = bedrock?.sessionToken ?? "";
+ values[ENV_KEYS.bedrockSmallLlmModel] =
+ bedrock?.smallLlmModel ?? BEDROCK_DEFAULT_SMALL_MODEL;
+ values[ENV_KEYS.bedrockLargeLlmModel] =
+ bedrock?.largeLlmModel ?? BEDROCK_DEFAULT_LARGE_MODEL;
+ values[ENV_KEYS.bedrockEmbeddingModel] =
+ bedrock?.embeddingModel ?? BEDROCK_DEFAULT_EMBEDDING_MODEL;
+}
+
+function fallbackEmbeddingDimensions(choices: InitChoices) {
+ const embeddingModel = resolveActiveEmbeddingModel(choices.models);
+ const known = lookupEmbeddingDimensions(embeddingModel);
+ if (known !== undefined) {
+ return {
+ nodesDimension: known,
+ tripletsDimension: known,
+ observationsDimension: known,
+ dataDimension: known,
+ relationshipsDimension: known,
+ };
+ }
+ if (choices.models.embeddingsProvider === "ollama") {
+ return OLLAMA_EMBEDDING_DIMENSIONS;
+ }
+ return EMBEDDINGS_DEFAULTS;
+}
+
+function applyEmbeddingDefaults(
+ values: Record<string, string | number | undefined>,
+ choices: InitChoices,
+): void {
+ values[ENV_KEYS.embeddingsSmallModel] = EMBEDDINGS_DEFAULTS.smallModel;
+ values[ENV_KEYS.embeddingsLocalModel] =
+ values[ENV_KEYS.embeddingsLocalModel] ?? EMBEDDINGS_DEFAULTS.localModel;
+
+ const embeddingDims = choices.models.embeddingDimensions ?? fallbackEmbeddingDimensions(choices);
+
+ values[ENV_KEYS.embeddingNodesDimension] = embeddingDims.nodesDimension;
+ values[ENV_KEYS.embeddingTripletsDimension] = embeddingDims.tripletsDimension;
+ values[ENV_KEYS.embeddingObservationsDimension] =
+ embeddingDims.observationsDimension;
+ values[ENV_KEYS.embeddingDataDimension] = embeddingDims.dataDimension;
+ values[ENV_KEYS.embeddingRelationshipsDimension] =
+ embeddingDims.relationshipsDimension;
+
+ if (choices.models.embeddingsProvider === "azure" && choices.models.azure) {
+ values[ENV_KEYS.embeddingsFullEndpoint] =
+ choices.models.azure.embeddingEndpoint;
+ values[ENV_KEYS.embeddingsKey] = choices.models.azure.embeddingKey;
+ } else {
+ values[ENV_KEYS.embeddingsFullEndpoint] =
+ values[ENV_KEYS.embeddingsFullEndpoint] ?? AZURE_EMBEDDING_PLACEHOLDER;
+ values[ENV_KEYS.embeddingsKey] =
+ values[ENV_KEYS.embeddingsKey] ?? AZURE_KEY_PLACEHOLDER;
+ }
+}
diff --git a/tui/src/types.ts b/tui/src/types.ts
new file mode 100644
index 0000000..c797d39
--- /dev/null
+++ b/tui/src/types.ts
@@ -0,0 +1,160 @@
+export type GraphDb = "networkx" | "neo4j";
+export type VectorDb = "postgresql" | "milvus";
+export type DataDb = "postgresql" | "mongo";
+export type ModelsMode = "local" | "remote";
+export type ModelProvider = "ollama" | "azure" | "openai" | "gcp_vertex" | "amazon_bedrock";
+export type OcrMode = "docparser" | "docling";
+export type PipelineMode = "accurate" | "lightweight";
+export type ServicesRuntime = "docker" | "manual";
+
+export function isPipelineMode(value: string): value is PipelineMode {
+ return value === "accurate" || value === "lightweight";
+}
+
+export interface DbChoices {
+ vectorDb: VectorDb;
+ dataDb: DataDb;
+ graphDb: GraphDb;
+}
+
+export interface OllamaChoices {
+ host: string;
+ port: number;
+ smallModel: string;
+ largeModel: string;
+ embeddingsLocalModel: string;
+}
+
+export interface GcpChoices {
+ credentialsPath: string;
+ projectId: string;
+ smallLlmModel: string;
+ largeLlmModel: string;
+ embeddingModel: string;
+}
+
+export interface AzureChoices {
+ smallLlmModel: string;
+ largeLlmModel: string;
+ llmApiVersion: string;
+ llmEndpoint: string;
+ llmSubscriptionKey: string;
+ embeddingEndpoint: string;
+ embeddingKey: string;
+ embeddingModel: string;
+}
+
+export interface OpenAIChoices {
+ apiKey: string;
+ baseUrl?: string;
+ smallLlmModel: string;
+ largeLlmModel: string;
+ embeddingModel: string;
+}
+
+export interface BedrockChoices {
+ region: string;
+ accessKeyId: string;
+ secretAccessKey: string;
+ sessionToken?: string;
+ smallLlmModel: string;
+ largeLlmModel: string;
+ embeddingModel: string;
+}
+
+export interface EmbeddingDimensions {
+ nodesDimension: number;
+ tripletsDimension: number;
+ observationsDimension: number;
+ dataDimension: number;
+ relationshipsDimension: number;
+}
+
+export interface ModelsChoices {
+ mode: ModelsMode;
+ llmSmallProvider: ModelProvider;
+ llmLargeProvider: ModelProvider;
+ embeddingsProvider: ModelProvider;
+ embeddingDimensions?: EmbeddingDimensions;
+ ollama?: OllamaChoices;
+ gcp?: GcpChoices;
+ azure?: AzureChoices;
+ openai?: OpenAIChoices;
+ bedrock?: BedrockChoices;
+}
+
+export interface PostgresConnection {
+ host: string;
+ port: number;
+ username: string;
+ password: string;
+ systemDatabase: string;
+ maintenanceDatabase: string;
+}
+
+export interface Neo4jConnection {
+ host: string;
+ port: number;
+ username: string;
+ password: string;
+}
+
+export interface MilvusConnection {
+ host: string;
+ port: number;
+ uri?: string;
+ token?: string;
+}
+
+export interface MongoConnection {
+ host: string;
+ port: number;
+ username: string;
+ password: string;
+}
+
+export interface RedisConnection {
+ host: string;
+ port: number;
+}
+
+export interface Connections {
+ redis: RedisConnection;
+ postgresql?: PostgresConnection;
+ neo4j?: Neo4jConnection;
+ milvus?: MilvusConnection;
+ mongo?: MongoConnection;
+}
+
+export interface AuthChoices {
+ brainpatToken: string;
+}
+
+export interface PipelineChoices {
+ ocrMode: OcrMode;
+}
+
+export interface InitChoices {
+ dbs: DbChoices;
+ models: ModelsChoices;
+ pipeline: PipelineChoices;
+ connections: Connections;
+ auth: AuthChoices;
+ servicesRuntime: ServicesRuntime;
+ usedDefaults: boolean;
+}
+
+export interface InstallState {
+ cloned: boolean;
+ venvCreated: boolean;
+ depsInstalled: boolean;
+ envWritten: boolean;
+ containersStarted: boolean;
+ selectedServices: string[] | null;
+ servicesRuntime: ServicesRuntime | null;
+ sourcePath: string;
+ repoUrl: string;
+ branch: string;
+}
+
+export type Platform = "darwin" | "linux" | "win32";
diff --git a/tui/tsconfig.json b/tui/tsconfig.json
new file mode 100644
index 0000000..1288bcb
--- /dev/null
+++ b/tui/tsconfig.json
@@ -0,0 +1,24 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "lib": ["ES2022"],
+ "outDir": "dist",
+ "rootDir": "src",
+ "strict": true,
+ "noImplicitAny": true,
+ "noUncheckedIndexedAccess": true,
+ "exactOptionalPropertyTypes": false,
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "allowSyntheticDefaultImports": true,
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "forceConsistentCasingInFileNames": true,
+ "verbatimModuleSyntax": false,
+ "declaration": false
+ },
+ "include": ["src/**/*.ts"],
+ "exclude": ["node_modules", "dist"]
+}
diff --git a/tui/tsup.config.ts b/tui/tsup.config.ts
new file mode 100644
index 0000000..e2b87d1
--- /dev/null
+++ b/tui/tsup.config.ts
@@ -0,0 +1,17 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+ entry: ["src/index.ts"],
+ format: ["esm"],
+ target: "node18",
+ platform: "node",
+ outDir: "dist",
+ clean: true,
+ splitting: false,
+ shims: true,
+ sourcemap: false,
+ minify: false,
+ banner: {
+ js: "#!/usr/bin/env node",
+ },
+});