{"id":30558233,"url":"https://github.com/llamasearchai/openbrain","last_synced_at":"2026-04-07T22:31:40.320Z","repository":{"id":311947152,"uuid":"1042318682","full_name":"llamasearchai/OpenBrain","owner":"llamasearchai","description":"OpenBrain: local-first brain model with FastAPI + React, metrics streaming, and agentic planning.","archived":false,"fork":false,"pushed_at":"2025-08-27T17:05:54.000Z","size":166406,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T01:26:24.794Z","etag":null,"topics":["3d","agents","brain","fastapi","llm","neuroscience","openbrain","react","threejs","typescript","vite"],"latest_commit_sha":null,"homepage":"https://github.com/llamasearchai/OpenBrain","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/llamasearchai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-21T20:31:00.000Z","updated_at":"2025-08-27T17:07:21.000Z","dependencies_parsed_at":"2025-08-28T01:28:58.001Z","dependency_job_id":"5f73d170-1fec-49b2-994a-ebea30099461","html_url":"https://github.com/llamasearchai/OpenBrain","commit_stats":null,"previous_names":["llamasearchai/openbrain"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/llamasearchai/OpenBrain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llamasearchai%2FOpenBrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llamasearchai%2FOpenBrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llamasearchai%2FOpenBrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llamasearchai%2FOpenBrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/llamasearchai","download_url":"https://codeload.github.com/llamasearchai/OpenBrain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/llamasearchai%2FOpenBrain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272466729,"owners_count":24939458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","agents","brain","fastapi","llm","neuroscience","openbrain","react","threejs","typescript","vite"],"created_at":"2025-08-28T08:03:03.432Z","updated_at":"2026-04-07T22:31:40.294Z","avatar_url":"https://github.com/llamasearchai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"OpenBrain.png\" alt=\"OpenBrain logo\" width=\"160\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/llamasearchai/OpenBrain/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://github.com/llamasearchai/OpenBrain/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.11%2B-blue\" alt=\"Python 3.11+\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-20.x-brightgreen\" alt=\"Node 20\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/docker-compose-blue\" alt=\"Docker Compose\" /\u003e\n\u003c/p\u003e\n\n# OpenBrain\n\nOpenBrain is a production-grade, local-first platform that renders an interactive human brain model in the browser, streams metrics from a FastAPI backend, and integrates agentic planning via LLM providers. The stack is tuned for local development and secure production deployment with observability.\n\n## Highlights\n- FastAPI backend with HTTP, WebSocket, metrics, and agent planning\n- React + Vite + TypeScript frontend with 3D rendering (Three.js / R3F)\n- Tests for backend (pytest) and frontend (Vitest + Testing Library)\n- Docker Compose stack with optional LiteLLM proxy and observability\n- Secure environment variable handling; no secrets in the repo\n\n## Repository Layout\n- `backend/app`: FastAPI API (`main.py`), agents (`agents.py`), config (`config.py`), CLI (`cli.py`)\n- `backend/tests`: Pytest suite (HTTP, WS, GLTF, agent mocks)\n- `web`: React + Vite + TypeScript app (`src/*`), Vitest tests\n- `deploy`: Compose stack, LiteLLM, observability configs\n- `scripts`: Developer convenience scripts\n- `ops`: Backup/restore helpers\n- `docs`: Production notes and architecture docs\n\n## Requirements\n- Python 3.11+\n- Node 20+\n- Docker (optional for full stack)\n\n## Quick Start (Local, no Docker)\n1) Backend setup\n```\npython3 -m venv backend/.venv\nsource backend/.venv/bin/activate\npip install -r backend/requirements.txt\n```\n\n2) Configure environment\n```\ncp .env.example .env\n# Edit .env and set OPENAI_API_KEY if you plan to use OpenAI\n# Optionally set OPENAI_BASE_URL to your LiteLLM proxy (defaults to http://127.0.0.1:4000)\n```\n\n3) Run API\n```\n(cd backend \u0026\u0026 uvicorn app.main:app --reload --host 127.0.0.1 --port 8000)\n```\n\n4) Frontend dev server\n```\n(cd web \u0026\u0026 npm ci \u0026\u0026 npm run dev)\n```\n\nVerify:\n- API: `curl http://127.0.0.1:8000/healthz`\n- Web: open http://127.0.0.1:5173\n\n## Quick Start (Docker Compose)\n```\n./scripts/ob.sh\n# or\ndocker compose -f deploy/compose.yml up -d\n```\n\nVerify:\n- API: `curl http://127.0.0.1:8000/healthz`\n- Web: http://127.0.0.1:5173\n- Metrics: http://127.0.0.1:8000/metrics\n\n## Assets\n- Primary model: `web/public/models/openbrain/brain.gltf`\n- Textures: `web/public/models/openbrain/textures/*`\n- Approx size: ~21 MB (well under GitHub’s 100 MB per-file limit)\n- Large-file handling: Git LFS is configured for model assets (see below). If you later add larger GLTF/GLB or textures, they will be tracked by LFS automatically.\n\n## Git LFS\nWe configure Git LFS to version large binary assets in `web/public/models/*`.\n\nQuick setup:\n```\ngit lfs install\ngit add .gitattributes\ngit add web/public/models/openbrain\ngit commit -m \"repo: track 3D assets with Git LFS\"\n```\n\n## Author\n- Nik Jois\n\n## Environment Variables\nCopy `.env.example` to `.env` and set values as needed.\n\n- `OPENAI_API_KEY`: Required to call OpenAI directly (optional if using LiteLLM)\n- `OPENAI_BASE_URL`: Base URL for OpenAI-compatible proxy (defaults to `http://127.0.0.1:4000`)\n- `ANTHROPIC_API_KEY`: Optional for Anthropic\n- `COHERE_API_KEY`: Optional for Cohere\n\nThe backend loads environment variables via Pydantic Settings (see `backend/app/config.py`). Secrets are never hard-coded.\n\n## Development\n- Backend\n  - Run: `(cd backend \u0026\u0026 uvicorn app.main:app --reload --host 127.0.0.1 --port 8000)`\n  - Tests: `pytest` (from repo root; `pytest.ini` configured)\n  - Coverage target: `backend/app`\n\n- Frontend\n  - Install/build: `(cd web \u0026\u0026 npm ci \u0026\u0026 npm run build)`\n  - Dev server: `(cd web \u0026\u0026 npm run dev)`\n  - Test/lint: `(cd web \u0026\u0026 npm test)` and `(cd web \u0026\u0026 npm run lint)`\n\n## Testing Strategy\n- Python: Pytest with FastAPI `TestClient`; external LLM calls are avoided/mocked in tests (see `backend/tests/test_agents_success.py`). No external network in tests.\n- Frontend: Vitest + jsdom + Testing Library; coverage configured in `web/vitest.config.ts`.\n\n## Security \u0026 Secrets\n- Do not commit secrets. `.env` is ignored by `.gitignore`.\n- Use `.env` locally and CI secrets in your pipeline provider.\n- If a secret was ever committed (e.g., `.env`), purge it from Git history:\n  - Prefer `git filter-repo`:\n    ```\n    pipx install git-filter-repo  # or brew install\n    git filter-repo --path .env --invert-paths\n    git push --force --tags origin main\n    ```\n  - Or use BFG Repo-Cleaner.\n- Consider Git LFS for very large assets (GLTF/FBX/textures) and/or host them via releases.\n\n## Production Readiness\n- CORS locked to localhost by default; configure allowed origins via env if needed\n- Metrics at `/metrics`; optional OpenTelemetry via env\n- Docker Compose for API, web, LiteLLM proxy, and observability\n- Small, pure functions; PEP 8, type hints in Python; ESLint/TS rules for web\n\nChecklist:\n- [ ] `.env` not committed; secrets stored in CI or secret manager\n- [ ] Backend unit/integration tests pass (`pytest`)\n- [ ] Frontend tests and lint pass (`npm test`, `npm run lint`)\n- [ ] Images/assets optimized; large assets managed via LFS or releases\n- [ ] Basic SLOs/metrics validated; health checks respond OK\n\n## Troubleshooting\n- On missing Python packages: activate the venv and reinstall requirements.\n- On frontend type issues: run `npm run lint` and `npm run build` to surface TS errors.\n- On LLM calls during tests: ensure env keys are unset or use mocks; tests shouldn’t hit network.\n\n## Contributing\nOpen an issue with context and repro steps. For PRs, use scope prefixes (e.g., `backend:`, `web:`) and include test evidence. CI must pass (`pytest`, `npm test`, `npm run lint`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllamasearchai%2Fopenbrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fllamasearchai%2Fopenbrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fllamasearchai%2Fopenbrain/lists"}