traverse-framework / traverse-framework/registry

Publish capability: core.extract-to-schema (structured extract into fixed JSON schema, fail closed)

Open
#498 0 comments 0 reactions 0 assignees View on GitHub
enhancement good first issue help wanted no-spec-needed
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.