docs: portable runbook and Diataxis index
Tests / Test (push) Skipped
Tests / Release (semver) (push) Skipped
Tests / Test (push) Skipped
Tests / Release (semver) (push) Skipped
Public face is a product, not a laptop tool. Run steps live in docs/runbook.md; decisions D3/D6/D14/D15/D17/D18 stay in the docs index.
This commit is contained in:
+26
-8
@@ -1,16 +1,34 @@
|
||||
# 2dph (deductionphile)
|
||||
---
|
||||
type: reference
|
||||
status: current
|
||||
related:
|
||||
- docs/runbook.md
|
||||
- docs/design.md
|
||||
- PLAN.md
|
||||
---
|
||||
|
||||
Evidence-first knowledge graph + hybrid RAG over the operational
|
||||
Brain/ops/eSlider stack. Facts need proof or they are
|
||||
# 2dph docs (Diataxis)
|
||||
|
||||
Evidence-first knowledge graph. Facts need proof or they are
|
||||
`(not confirmed)`.
|
||||
|
||||
- [PLAN.md](../PLAN.md) — decisions, execution order, open questions (v2)
|
||||
- [design](design.md) — schema, deduction model, sources
|
||||
- [reasoner](reasoner.md) — D18 CPU bake-off (Qwen3.5-9B vs Bonsai / Qwen3.6-27B)
|
||||
- [Gitea issues](https://git.produktor.io/eSlider/2dph/issues) — work board (origin)
|
||||
| Type | Doc |
|
||||
|------|-----|
|
||||
| tutorial / howto | [runbook](runbook.md) — run anywhere (uv, Go, Docker) |
|
||||
| explanation | [design](design.md) — two roots, deduction, D17/D20/D18 |
|
||||
| howto | [picoclaw](picoclaw.md) — MCP agent profile |
|
||||
| howto | [reasoner](reasoner.md) — CPU bake-off (D18) |
|
||||
| reference | [PLAN.md](../PLAN.md) — decisions D1–D21 |
|
||||
|
||||
Decisions the public face must name: **D3** SearXNG compose, **D6** Go service /
|
||||
Python write sidecar, **D14** `bin/{subject}/{method}.go`, **D15** Gitea origin,
|
||||
**D17** assertion gate (facts → info → web), **D18** pluggable reasoner.
|
||||
|
||||
Search: `bin/brain/search.go "query"` (HTTP: `bin/brain/serve.go` —
|
||||
`/health` `/search` `/get` `/stats` `/audit` `/ingest`). `--hop` is
|
||||
not a walk; the flag errors until File/FROM_FILE edges exist.
|
||||
|
||||
Published docs live here and mirror the project state.
|
||||
Work board: [Gitea issues](https://git.produktor.io/eSlider/2dph/issues).
|
||||
PRs and CI: GitHub [`eSlider/2dph`](https://github.com/eSlider/2dph).
|
||||
|
||||
Published docs live here and match live commands.
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
---
|
||||
type: explanation
|
||||
status: current
|
||||
related:
|
||||
- docs/README.md
|
||||
- docs/runbook.md
|
||||
---
|
||||
|
||||
# Design — facts, info, deduction
|
||||
|
||||
## Two roots, one transaction
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
type: howto
|
||||
status: current
|
||||
related:
|
||||
- docs/README.md
|
||||
- PLAN.md
|
||||
---
|
||||
|
||||
# Run 2dph (portable)
|
||||
|
||||
No laptop-absolute paths. Config lives in env files under `$HOME/.config/brain/`
|
||||
(mode 0600), not in git.
|
||||
|
||||
## Toolchain
|
||||
|
||||
- Go (see `go.mod`)
|
||||
- Python 3.12 + [uv](https://docs.astral.sh/uv)
|
||||
- Optional: Docker, Zig CGO via `bin/cgo/zig` (not gcc)
|
||||
|
||||
```bash
|
||||
uv venv .venv
|
||||
uv pip install -r requirements.lock.txt
|
||||
eval "$(bin/cgo/zig env)" # when compiling Ladybug read tools
|
||||
go test ./...
|
||||
uv run python -m unittest discover -s bin/tools -t .
|
||||
```
|
||||
|
||||
## Config
|
||||
|
||||
| File / env | Purpose |
|
||||
|------------|---------|
|
||||
| `$BRAIN_SEARCH_ENV` (default `$HOME/.config/brain/search.env`) | `BRAIN_SEARCH_URL` (SearXNG). Optional Basic Auth. |
|
||||
| `$HOME/.config/brain/db-profiles.yml` | read-only Postgres profiles (OnlyOffice via tunnel) |
|
||||
|
||||
If the host already runs SearXNG, point `BRAIN_SEARCH_URL` at it. Do not start
|
||||
a second copy (D3). Optional Compose instance:
|
||||
|
||||
```bash
|
||||
SEARXNG_SECRET=$(openssl rand -hex 32) docker compose --profile searxng up -d
|
||||
```
|
||||
|
||||
That binds `127.0.0.1:8888`. JSON format must stay enabled.
|
||||
|
||||
## Index then search
|
||||
|
||||
Write path is Compose profile `index` (Python Ladybug rebuild) until
|
||||
`brain/add` is v2. The operator command is `bin/brain/index.go`.
|
||||
|
||||
```bash
|
||||
bin/brain/index.go --rebuild
|
||||
bin/brain/search.go "LadybugDB vector index" # facts → info → web (D17)
|
||||
bin/brain/search.go "upstream flag" --no-web
|
||||
bin/brain/get.go <id> --body
|
||||
bin/brain/stats.go
|
||||
```
|
||||
|
||||
`--hop` is not implemented. Empty web results are `throttled`, not absence.
|
||||
|
||||
Ladybug 0.19: never `DROP INDEX` FTS/VECTOR (ghost catalog). Fresh indexes =
|
||||
delete `var/kb.lbug` then `--rebuild`.
|
||||
|
||||
## HTTP / MCP
|
||||
|
||||
```bash
|
||||
docker compose up -d brain # :8630 Zig CGO serve
|
||||
docker compose --profile index run --rm index # rebuild
|
||||
docker compose --profile picoclaw up brain-mcp # MCP 127.0.0.1:8630
|
||||
```
|
||||
|
||||
`GET /openapi.json`, `POST /mcp`. Agent tool order: `search` → `get` → `audit`.
|
||||
|
||||
## Reasoner (optional, D18)
|
||||
|
||||
CPU sidecar on `127.0.0.1:11435`. Weights are not in the 2dph image.
|
||||
|
||||
```bash
|
||||
docker compose --profile reasoner up -d reasoner
|
||||
REASONER_BASE_URL=http://127.0.0.1:11435/v1 ./bin/reasoner/bakeoff.go --json
|
||||
```
|
||||
|
||||
See [reasoner.md](reasoner.md).
|
||||
Reference in New Issue
Block a user