{
  "markdown": "# Wrangles Docs\n\nDocumentation and Registry compilation for the Wrangles platform. The planned\nRegistry brings together catalog identities, executable contracts and editorial\ncontent to produce complete, versioned reference material for people and tools.\n\n## Planned Registry design\n\n**Status: design in review.** [Issue #32](https://github.com/wrangleworks/Wrangles-Docs/issues/32)\ntracks the redesign. The architecture below describes the intended direction;\nit does not indicate that database changes, new APIs or consumer cutover have\nbeen implemented or deployed.\n\nEach fact has one authoring owner. API Core supplies catalog information,\nWranglesPY supplies the executable contract, and Docs supplies explanations and\nexamples. The compiler joins pinned inputs and reports conflicts instead of\nsilently choosing between competing definitions.\n\n```mermaid\nflowchart TB\n    subgraph sources[Authoritative sources]\n        catalog[\"API Core catalog<br/>Identities, kinds, names, classifications and bindings\"]\n        runtime[\"WranglesPY<br/>Executable contracts and shared controls\"]\n        editorial[\"Wrangles Docs<br/>Compact Markdown, guidance and example fixtures\"]\n    end\n\n    subgraph publication[Public publication pipeline]\n        approved[\"Approved public catalog snapshot\"]\n        compiler[\"Registry compiler<br/>Pinned revisions, reconciliation and checksums\"]\n        bundle[\"Versioned public Registry artifacts\"]\n        reference[\"Grouped reference pages<br/>Parameter tables, metadata and examples\"]\n        schemas[\"Recipe schemas and complete machine contracts\"]\n    end\n\n    subgraph authorized[Authorized model access]\n        metadata[\"Live saved-model metadata<br/>Model access required\"]\n        preview[\"Versioned training/reference preview<br/>Content-read permission required\"]\n    end\n\n    rai[\"Rai / WranglesAgent<br/>Combines pinned capabilities with authorized model context\"]\n\n    catalog -->|Publication allowlist| approved\n    approved --> compiler\n    runtime -->|Pinned contract export| compiler\n    editorial --> compiler\n    compiler --> bundle\n    bundle --> reference\n    bundle --> schemas\n    bundle -->|Pinned bundle| rai\n    catalog --> metadata\n    catalog -->|Derived from exact saved content| preview\n    metadata --> rai\n    preview --> rai\n```\n\nPrivate model metadata and training/reference previews do not enter the public\ncompiler inputs or published bundle. Rai combines them with the public Registry\nat request time under the caller's authorization.\n\n### Ownership and authoring\n\n| Owner | Authored or generated responsibility |\n| --- | --- |\n| API Core | Central `catalog_id`, existing model identities, names, catalog tags, normalized classifications, explicit catalog-to-contract bindings, model notes/status, publication policy and access. The shared-catalog proposal adds `kind` and typed relationships here. |\n| WranglesPY | One structured executable contract maintained with the implementation: callable keys, parameters, defaults, enums, nested and conditional constraints, supported forwarded arguments, output semantics, runtime prerequisites and shared controls. |\n| Wrangles Docs | Small catalog references, capability descriptions, explanatory prose, parameter-help supplements, curated recipes and input/output fixtures. |\n| Registry compiler | Reconciled reference pages, recipe schemas, complete machine contracts and discovery artifacts, with source revisions and checksums. These are generated projections, not additional authoring sources. |\n| Rai / WranglesAgent | Consumer compatibility and eligibility checks, authorized model selection and explicit execution binding. |\n\nMechanical signature facts are derived from Python; constraints that signatures\ncannot express remain explicit in the structured contract. Python documentation\nstays concise and useful to Python callers. Docs imports the contract rather\nthan maintaining another full parameter schema in Markdown frontmatter.\n\nThe contract must cover recipe wrangles, connector read/write/run operations,\nthe recipe envelope and shared controls. WranglesPY does not depend on Docs to\ngenerate its own contract. Physical contract format and remaining lifecycle\nownership details are design decisions tracked in #32.\n\n### One catalog, explicit kinds and bindings\n\nThe API Core `models` table is the complete wrangle identity catalog, including\nStock and Recipe Wrangles. The preferred proposal extends the same identity\nnamespace to connectors, run capabilities and selected reusable concepts.\nWhether this uses the existing table directly or a small catalog core linked\nto model-specific data remains open.\n\n- **Catalog identity:** centrally allocate immutable positive 64-bit integer\n  `catalog_id` values. Backfill existing entries, never reuse IDs, allow gaps,\n  and preserve identities across imports and environments. The proposed wire\n  format is a canonical decimal string so JavaScript cannot round a BIGINT.\n  Other environments must use the central allocator rather than independent\n  overlapping counters.\n- **Existing behavior:** retain `models.id`, execution `model_id`, saved recipes\n  and legacy APIs. A catalog selection resolves to an explicit callable binding\n  and, where applicable, the selected saved-model ID. A generic `.custom`\n  wrapper's identity must never become the selected model's ID.\n- **Customer terminology:** Type primarily projects database `purpose`\n  (Extract, Classify, Map for `schema`, and so on). Variant combines family\n  (DIY, Stock, Bespoke) with an applicable AI subtype. Technical implementation\n  tags such as `v2`, Registry `kind` and model readiness remain separate.\n- **Identity granularity:** the proposal gives a connector family and its\n  independently documented read/write/run operations distinct entries, joined\n  by a typed relationship such as `belongs_to`. A recipe concept, an executable\n  recipe callable and a saved recipe instance are also distinct. Concepts may\n  have no execution binding; not every documentation heading needs an identity.\n- **Kind-aware compatibility:** backfill verified kinds on existing rows and\n  deploy explicit eligibility filters before adding non-model records. Legacy\n  model listing, detail, training and execution paths must not treat connectors\n  or concepts as trainable saved models, apply model defaults to them or hydrate\n  nonexistent content versions. Type/Variant, readiness and training/content\n  fields apply only to appropriate kinds; other entries need no invented model\n  values.\n\nThe proposed typed relationships are authored once in API Core and use catalog\nIDs at both ends. Public exports must validate target existence, compatible\nversions and publication eligibility without exposing private targets.\n\n### Saved-model previews and version boundaries\n\nAPI Core derives a small preview from each applicable saved model's original\ntraining/reference content. It includes ordered original column names, up to\nfive representative rows, the total row count and the exact content version.\nPositional rows preserve column order and duplicate names; blanks and value\ntypes must also be preserved.\n\nGeneration must be deterministic and bounded, with explicit empty and\nunavailable states. Associate the original input with the finalized content\nversion, refresh on content changes, and resolve latest, production or historic\nselection to that exact version. Deletion and permission revocation must also\ninvalidate access to cached previews. Sampling and payload limits remain part\nof the preview contract review.\n\nPreview access requires permission to inspect the underlying content; model\nlisting alone is insufficient. Keep previews behind a separate authorized API\nresponse and exclude settings, credentials and private routing information.\nReference columns describe the saved model's data, not the customer's recipe\ninput/output columns.\n\nA preview version is evidence about the displayed content, **not an execution\npin**. Execution-version behavior needs separate verification. Runtime package\nversions, Registry releases, contract schema versions, saved-content versions\nand implementation tags must remain distinct.\n\n### Generated output and adoption\n\nPreserve the grouped Extract reference with its parameter tables, metadata and\nexamples. Generate sample tables from curated fixtures. Machine consumers must\nreceive complete constraints and useful examples; bounded discovery summaries\nmust not silently replace full contract retrieval.\n\nAdopt the redesign in focused stages:\n\n1. **API Core:** settle entity kinds and storage, validate legacy filters, add\n   identity allocation/backfill, normalized projections and versioned previews.\n2. **WranglesPY:** introduce the shared executable contract and verify parity\n   across wrangles, connectors, run operations and recipe structures.\n3. **Docs:** simplify authoring inputs and compile pinned sources into the\n   familiar reference and complete consumer artifacts.\n4. **WranglesAgent:** introduce versioned readers, explicit catalog bindings\n   and authorized previews, with compatibility and permission checks.\n5. **Migration and cutover:** validate old recipes, lossless IDs, permission\n   isolation, version changes, artifact completeness and rollback. Retain\n   compatible readers/bundles during transition; allocated IDs remain stable.\n\nRaw Stock Extract, Recipe Wrangle and current DIY/AI mappings still require\nrepresentative sanitized records. The supplied database sample established\nBespoke/Classify with technical `v2` only. The training-finalization integration,\nentity taxonomy and physical catalog storage also need review before\nimplementation. Temporary database transition scripts are not workflow or\nauthoring authorities.\n\n## Current repository and related work\n\nThe existing Registry tooling remains pre-production. See\n[registry/README.md](registry/README.md) for current directories and commands,\nand [registry/CONTRACT.md](registry/CONTRACT.md) for the current 0.2 contract.\nThose documents retain earlier UUID and schema-ownership migration assumptions;\nthey do not describe the revised ownership proposed above. Updating those\ncontracts and generators belongs to the implementation stages.\n\n- [#32 - Registry redesign](https://github.com/wrangleworks/Wrangles-Docs/issues/32):\n  design decisions, evidence gaps and review.\n- [#30 - Content work](https://github.com/wrangleworks/Wrangles-Docs/issues/30):\n  remains paused pending design alignment.\n- [#31 - Optional guides](https://github.com/wrangleworks/Wrangles-Docs/issues/31):\n  future additions that complement the grouped reference.\n- [#27 - Production cutover](https://github.com/wrangleworks/Wrangles-Docs/issues/27):\n  separate migration and deployment gates.\n",
  "bytes": 10744,
  "sha": "538d1d6b6b19469543100c9a348ac004aac957c4927cdb0f6006a19eaae094f5",
  "repo_slug": "wrangleworks/wrangles-docs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_wrangleworks_wrangles_docs_registry_inde_2e7dd2f4/readme"
}