traverse-framework / traverse-framework/registry
Publish capability: core.extract-to-schema (structured extract into fixed JSON schema, fail closed)
- Dominant language
- Rust
- Stars
- 1
- Forks
- 1
- Avg merge
- 1h 17m
- Merged PRs (30d)
- 217
Description
## Why
Agents often free-form chat when the runtime actually needs **fields conforming to a fixed JSON schema** (order id, amount, currency, email). Closest relatives (`core.extract-action-items`, `text.detect-entities`) are different shapes. We need extract-**into-schema** with **validation fail closed** — AI-bounded if a model is used, otherwise honest heuristics only.
## One-PR ask
Publish **`core.extract-to-schema@1.0.0`**:
**Inputs:**
- `text`: string (source)
- `target_schema`: JSON Schema object (Draft 2020-12 subset — document which keywords you support: `type`, `properties`, `required`, `enum`, `minimum`/`maximum`, `minLength`/`maxLength` at minimum)
- `method`: `"heuristic"` | `"model"` (see host notes)
- `policy_version`: string
**Outputs:**
- `value`: object | null
- `valid`: boolean
- `errors`: array of `{ "path", "message", "code" }` (empty when valid)
- `uncertainty`: `"none"|"low"|"high"` (required; never silent invent)
- `ok`: boolean
- `reason_code`: e.g. `ok` | `schema_invalid` | `extract_failed` | `validation_failed` | `model_unavailable`
**Behavior:**
- Always validate extracted candidate against `target_schema`.
- On any validation failure → `valid: false`, `value: null` (fail closed); prefer no partial objects for v1.
- If `method=heuristic`: regex/key-value heuristics only; when unsure set `uncertainty` high and fail closed rather than inventing.
- If `method=model`: must declare contract `ai.model_backed` + models list; still fail closed on schema miss. **No free-form chat string as the primary output.**
Follow [`CONTRIBUTING.md`](https://github.com/traverse-framework/registry/blob/main/CONTRIBUTING.md) and [`capabilities/README.md`](https://github.com/traverse-framework/registry/blob/main/capabilities/README.md) publish checklist.
- Include `capability-src/` with real Rust tests meeting registry coverage gates (`functions` 100%, lines/regions ≥ 95%)
- Use `traverse-cli capability publish` (or the documented scaffold) so `artifact.digest` / `artifact.url` survive
- Declare `authoring.method` (`human` or `llm-assisted`)
- Ensure every `use_cases[].persona_ref` resolves (scaffold personas if needed)
- Run `bash scripts/ci/pre_pr_check.sh ` before opening
- One capability per PR; branch from `origin/main`, not another `publish/*` branch
**Apps are not ready — publish the capability only.** No app wiring, no demo product surface.
## Out of scope
- Generic "return any JSON" utilities
- Open-ended document Q&A
- Replacing `core.extract-action-items` / NER caps
## Done when
- CI green; published in next index
- Tests prove fail closed on schema miss; at least one happy-path extract for a frozen demo schema in use_cases
- If model path ships, `ai` block present and tests cover model-unavailable fail closed (mock/harness ok)
## Host / deps notes
**Prefer pure heuristic WASM** (`network_access: forbidden`) for v1 so first contributors need no connector. If you include `method=model`, you **must** document the inference host/connector pattern that already exists in-repo (or keep model weights in-WASM like `text.detect-entities`) — do **not** invent ambient network access. Honest README/contract notes required.
## Labels
`help wanted` · `good first issue` · `enhancement` · `no-spec-needed`
Contributor guide
Research direction
Start with CONTRIBUTING.md and capabilities/README.md, then inspect the documented scaffold or capability publish entry point and the existing capability-src/ examples. Implement the specified extract, schema-validation, and fail-closed behavior with real Rust tests, including a happy path and schema miss; run the coverage gates and bash scripts/ci/pre_pr_check.sh . Done means the capability is published with its digest and URL, resolved persona references, and green CI.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, rust, wasm
- Domain
- backend-api-design, build-system, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100