111 lines
3.3 KiB
Markdown
111 lines
3.3 KiB
Markdown
# amduat-app-next (Scaffold)
|
|
|
|
Starter project scaffold for building an app against `amduatd` v2.
|
|
|
|
## Included handoff assets
|
|
|
|
- `docs/v2-app-developer-guide.md` (compact app guide)
|
|
- `contracts/amduatd-api-contract.v2.json` (machine contract)
|
|
- `scripts/graph_client_helpers.sh` (reusable shell helpers)
|
|
|
|
## Quick start
|
|
|
|
1. Configure environment:
|
|
|
|
```sh
|
|
cp config/env.example config/env.local
|
|
```
|
|
|
|
2. Start a local daemon:
|
|
|
|
```sh
|
|
./scripts/dev_start_daemon.sh
|
|
```
|
|
`dev_start_daemon.sh` initializes the store for the selected backend and, when
|
|
`STORE_BACKEND=index`, runs a quick startup write probe. If index writes are
|
|
unhealthy, it first tries a one-time index store repair (backup + re-init) and
|
|
then falls back to `fs` if still unhealthy (configurable via
|
|
`INDEX_BACKEND_PROBE`, `INDEX_BACKEND_REPAIR`, and `INDEX_BACKEND_FALLBACK` in
|
|
`config/env.local`).
|
|
|
|
3. Run startup checks against the daemon socket:
|
|
|
|
```sh
|
|
./scripts/bootstrap_check.sh
|
|
```
|
|
|
|
4. Run sample idempotent batch ingest:
|
|
|
|
```sh
|
|
./scripts/ingest_example.sh
|
|
```
|
|
|
|
5. Run sample changes consumer (recommended):
|
|
|
|
```sh
|
|
./scripts/v2_app.sh consume-changes
|
|
```
|
|
|
|
## v2 Vertical Slice CLI
|
|
|
|
Use the integrated v2 app flow wrapper:
|
|
|
|
```sh
|
|
./scripts/v2_app.sh startup-check
|
|
./scripts/v2_app.sh ai-vertical-slice
|
|
./scripts/v2_app.sh ai-vertical-slice --skip-evals
|
|
./scripts/v2_app.sh ai-vertical-slice --auto-start-daemon
|
|
./scripts/v2_app.sh ai-agent 'doc-ai-1' 'What domain is doc-ai-1 in?' 'ms.within_domain'
|
|
./scripts/v2_app.sh ai-agent --json --require-evidence --max-steps 3 'doc-ai-1' 'What domain is doc-ai-1 in?' 'ms.within_domain'
|
|
./scripts/v2_app.sh ai-check
|
|
./scripts/v2_app.sh ai-generate 'Summarize retrieval behavior in one sentence.'
|
|
./scripts/v2_app.sh ai-generate --json 'Summarize retrieval behavior in one sentence.'
|
|
./scripts/v2_app.sh ai-answer 'doc-1' 'What topic is doc-1 in?' 'ms.within_domain'
|
|
./scripts/v2_app.sh ai-answer --json 'doc-1' 'What topic is doc-1 in?' 'ms.within_domain'
|
|
./scripts/v2_app.sh ai-answer --json --require-evidence 'doc-1' 'What topic is doc-1 in?' 'ms.within_domain'
|
|
./scripts/v2_app.sh ingest '{"idempotency_key":"k1","mode":"continue_on_error","nodes":[{"name":"doc-1"}]}'
|
|
./scripts/v2_app.sh sync-once
|
|
./scripts/v2_app.sh consume-changes --once
|
|
./scripts/v2_app.sh retrieve 'doc-1' 'ms.within_domain'
|
|
./scripts/v2_app.sh tombstone '<edge_ref>'
|
|
```
|
|
|
|
AI lane notes:
|
|
|
|
- Plan and scope guardrails: `docs/ai-plan.md`
|
|
- Deterministic seed payload: `ai/fixtures/seed_batch.json`
|
|
- Agent loop checkpoints: `ai/runs/agent-run-*.json`
|
|
|
|
Run integration coverage (requires running `amduatd` + `jq`):
|
|
|
|
```sh
|
|
./tests/integration_v2.sh
|
|
```
|
|
|
|
Run local cursor/handler semantics checks (no daemon required):
|
|
|
|
```sh
|
|
./tests/changes_consumer_410.sh
|
|
./tests/changes_consumer_handler.sh
|
|
```
|
|
|
|
Run AI connectivity and generation smoke eval (no daemon required):
|
|
|
|
```sh
|
|
./tests/ai_eval.sh
|
|
./tests/ai_answer_eval.sh
|
|
```
|
|
|
|
Run a fast end-to-end smoke (startup + ingest + sync + retrieve + tombstone):
|
|
|
|
```sh
|
|
./scripts/smoke_v2.sh
|
|
```
|
|
|
|
## Notes
|
|
|
|
- This scaffold assumes local Unix-socket access to `amduatd`.
|
|
- Graph cursors are opaque and must be persisted exactly as returned.
|
|
- `./scripts/sync_loop.sh` and `sync-loop` CLI are deprecated compatibility aliases.
|
|
- Keep `contracts/amduatd-api-contract.v2.json` in sync with upstream when you pull updates.
|