traverse-framework / traverse-framework/registry

CREATIVE: Publish core.invoice-line-normalize (invoice line-item normalizer to schema)

Open
#507 0 comments 0 reactions 0 assignees View on GitHub
enhancement help wanted no-spec-needed
Dominant language
Rust
Stars
1
Forks
1
Avg merge
1h 17m
Merged PRs (30d)
217

Description

## Why (creative vignette)

AP agents receive messy line items (free-text descriptions, mixed quantity fields). Creative ask: **normalize line items into a fixed invoice schema** (description, quantity, unit_price, currency, optional tax_code) with validation fail closed — agent proposes, capability accepts only schema-valid lines.

## Guardrails (required)

- Machine-readable contract
- Deterministic normalization rules OR fail-closed with explicit uncertainty — **no silent LLM invent of amounts**
- Tests + publish checklist
- Not a thin "LLM returns JSON string" wrapper
- Not a generic JSON util — must be invoice-line shaped
- Business domain

## One-PR ask

Publish **`core.invoice-line-normalize@1.0.0`**:

**Suggested contract:**
- Inputs: `raw_lines` array with loosely typed fields you document; frozen invoice line target schema (or embedded schema); `policy_version`
- Outputs: `lines` normalized array; `rejected` array of `{ "index", "reason_code" }`; `ok` (prefer fail closed for v1 money fields rather than silent partial money invent)
- Rules: coerce numeric strings with documented decimal policy; refuse currency mismatch; never invent missing unit_price

Creative freedom: B2B vs marketplace invoice vignettes OK within guardrails.

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

- Full OCR / PDF invoice parsing pipelines
- General-purpose JSON reshape utilities
- Payment posting

## Done when

- CI green; published in next index
- Tests: happy normalize, reject missing price, currency conflict, quantity coerce
- Uncertainty/fail-closed behavior documented for ambiguous raw fields

## Host / deps notes

**Pure WASM** heuristics. If you add a model path for description cleanup only, amounts must still be deterministic/fail-closed and `ai` must be declared — prefer no model for v1.

## Labels

`help wanted` · `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 traverse-cli capability publish flow and the capability-src Rust test layout. Run bash scripts/ci/pre_pr_check.sh against the draft PR body and verify the published artifact retains its digest and URL, persona references resolve, coverage gates pass, and the required normalization and rejection cases are covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, rust, wasm
Domain
backend-api-design, build-system, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.