SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: OS release prep - bootstrap script, deps, docs

Browse Source 
- Fix bootstrap script (.env.example.local → .env.example)
- Fix @langchain/core version conflict (^1.0.1 → ^0.3.0)
- Add settings:open event listener for LocalKeyGate button
- Pin Next.js to 15.1.3 (was "latest")
- Default runtime to 'local' mode
- Remove desktop app references from UI text
- Rewrite MCP docs for web-only context
- Add SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md
- Add docs/README.md, docs/TROUBLESHOOTING.md
- Update README with platform support table

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
“BeeRad”
2025-12-30 12:24:56 +11:00
co-authored by Claude Opus 4.5
parent ffbd47563e
commit 0e6bf12ad3
15 changed files with 394 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+88 -31
View File
@@ -1,64 +1,121 @@
# RA-H Open Source
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
A local-first research workspace with the complete RA-H three-panel interface, vector search, content ingestion, workflows, and conversation agents. This edition removes the Mac packaging, hosted authentication, and subscription backend so you can run everything locally with your own API keys.
## Platform Support
| Platform | Status | Notes |
|----------|--------|-------|
| **macOS (Apple Silicon)** | ✅ Fully Supported | M1/M2/M3/M4 Macs |
| **macOS (Intel)** | ✅ Fully Supported | Pre-2020 Macs |
| **Linux** | 🚧 Coming Soon | Requires manual sqlite-vec build |
| **Windows** | 🚧 Coming Soon | Requires manual sqlite-vec build |
> **Note:** The bundled `sqlite-vec` and `yt-dlp` binaries are macOS-only. Linux/Windows users can still run the app but need to compile sqlite-vec manually. See [Advanced Setup](#advanced-setup-linuxwindows) below.
## Features
- **3-Panel interface** – Explore nodes, focus, and chat with the orchestrator in one view.
- **Bring-your-own keys** – Works with your Anthropic/OpenAI keys only; nothing is sent to RA-H.
- **Local SQLite + sqlite-vec** – Semantic search, workflows, and memories run on your machine.
- **Content extraction** – YouTube, PDF, and web extraction pipelines included.
- **Extensible workflows** – Integrate workflow + tool registry ship intact for further hacking.
- **3-Panel interface** – Explore nodes, focus, and chat with the orchestrator in one view
- **Bring-your-own keys** – Works with your Anthropic/OpenAI keys only; nothing is sent to RA-H
- **Local SQLite + sqlite-vec** – Semantic search, workflows, and embeddings run on your machine
- **Content extraction** – YouTube, PDF, and web extraction pipelines included
- **Extensible workflows** – Integrate workflow + tool registry ship intact for further hacking
- **MCP Server** – Connect Claude, ChatGPT, or any MCP-compatible assistant to your knowledge graph
## Getting Started
### Prerequisites
- Node.js 20+
- npm 10+
- SQLite with `sqlite-vec` extension (prebuilt macOS binary is under `vendor/sqlite-extensions/vec0.dylib`; see `docs/2_schema.md` for build instructions on Linux/Windows)
- Node.js 18+
- npm 9+
- macOS (for pre-built sqlite-vec binary)
### Install & Bootstrap
```bash
git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
npm install
scripts/dev/bootstrap-local.sh # seeds SQLite schema + local env template
npm run dev # http://localhost:3000
npm rebuild better-sqlite3
scripts/dev/bootstrap-local.sh
npm run dev
```
When the UI loads, open **Settings → API Keys** and paste your OpenAI/Anthropic keys. They are stored locally via `src/services/storage/apiKeys.ts`.
Open http://localhost:3000, then go to **Settings → API Keys** and add your OpenAI/Anthropic keys.
### Environment
- `.env.example` documents every supported variable and defaults to `NEXT_PUBLIC_DEPLOYMENT_MODE=local`.
- Custom database paths: set `SQLITE_DB_PATH` and `SQLITE_VEC_EXTENSION_PATH`.
- No `.env.local` ships with the repo—run the bootstrap script to create yours.
- `.env.example` documents all supported variables
- Run the bootstrap script to create `.env.local`
- Custom paths: set `SQLITE_DB_PATH` and `SQLITE_VEC_EXTENSION_PATH`
## Project Layout
```
app/ Next.js App Router entrypoints
components/ UI building blocks (auth/tauri removed)
docs/ Architecture + schema docs (updated for local mode)
scripts/ Local dev helpers (bootstrap, sqlite backup/restore, audits)
src/services/ Agents, embeddings, ingestion, storage, workflows
vendor/sqlite-extensions/vec0.dylib macOS sqlite-vec build
src/
components/ UI building blocks
services/ Agents, embeddings, ingestion, storage, workflows
tools/ Agent tools (queryNodes, etc.)
config/ Prompts, workflows
apps/mcp-server/ MCP server for external AI assistants
docs/ Architecture + schema docs
scripts/ Local dev helpers (bootstrap, sqlite backup/restore)
vendor/ Pre-built binaries (sqlite-vec, yt-dlp)
```
## Development Scripts
- `npm run dev` – Local Next.js dev server (local mode forced)
- `npm run build` / `npm start` – Production build/start in local-only mode
- `npm run lint`, `npm run type-check` – Quality gates
- `npm run sqlite:backup` / `npm run sqlite:restore` – Database snapshots
| Command | Description |
|---------|-------------|
| `npm run dev` | Local dev server at localhost:3000 |
| `npm run build` | Production build |
| `npm run type-check` | TypeScript validation |
| `npm run lint` | ESLint check |
| `npm run sqlite:backup` | Database snapshot |
| `npm run sqlite:restore` | Restore from backup |
## Documentation
- `docs/0_overview.md` – Product background
- `docs/1_architecture.md` – Agents, tools, and workflow internals
- `docs/2_schema.md` – SQLite schema + sqlite-vec setup
- `docs/4_tools-and-workflows.md` – Tool registry + workflow guide
- `docs/9_open-source.md` – Local BYO-key process tracking
Private runbooks, Supabase CRM docs, and Mac packaging instructions were removed from this tree. See `docs/os_docs/2025-02-09-open-source-porting-notes.md` for details on what was changed from the private repo.
- [docs/README.md](docs/README.md) – Documentation index
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) – Common issues and fixes
- [docs/0_overview.md](docs/0_overview.md) – Product background
- [docs/1_architecture.md](docs/1_architecture.md) – Technical architecture
- [docs/2_schema.md](docs/2_schema.md) – Database schema + sqlite-vec
- [docs/8_mcp.md](docs/8_mcp.md) – MCP server setup
## Advanced Setup (Linux/Windows)
The app works on Linux/Windows but requires manually compiled binaries:
### sqlite-vec (required for vector search)
1. Clone: https://github.com/asg017/sqlite-vec
2. Build for your platform (see their README)
3. Place binary at:
- Linux: `vendor/sqlite-extensions/vec0.so`
- Windows: `vendor/sqlite-extensions/vec0.dll`
4. Update `SQLITE_VEC_EXTENSION_PATH` in `.env.local`
### yt-dlp (required for YouTube extraction)
1. Download from: https://github.com/yt-dlp/yt-dlp/releases
2. Place at `vendor/bin/yt-dlp` (or `yt-dlp.exe` on Windows)
3. Make executable: `chmod +x vendor/bin/yt-dlp` (Linux)
**What works without sqlite-vec:** UI, node CRUD, basic search, chat, content extraction
**What requires sqlite-vec:** Semantic/vector search, embedding-based agent tools
## Contributing
Issues and PRs are welcome! Please open a draft PR with context on the feature/fix, list any new environment requirements, and include manual test notes. See `CONTRIBUTING.md` for the lightweight guidelines.
Issues and PRs are welcome! Please read:
- [CONTRIBUTING.md](CONTRIBUTING.md) – Contribution guidelines
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) – Community standards
- [SECURITY.md](SECURITY.md) – Vulnerability reporting
## License
Released under the [MIT License](LICENSE). By contributing you agree that your code is provided under the same license.
Released under the [MIT License](LICENSE).