Structured Output Cleaner

Deterministic-first MVP for repairing narrowly scoped JSON-like structured output into machine-usable JSON with an explicit repair report.

Scope

This is a narrow workflow-repair utility. It does:

• strip code fences
• extract a single obvious JSON object/array from wrapper text
• repair a limited tested set of malformed JSON issues
• apply lightweight top-level schema coercion
• report what changed and what remains unresolved

Current tested repair coverage:

• code fences
• wrapper-text extraction when one obvious JSON block exists
• unquoted keys
• single-quoted strings
• trailing commas
• invalid backslashes inside strings

It does not:

• invent missing values
• choose between multiple plausible JSON blocks
• silently accept duplicate-key ambiguity
• silently overwrite data during field mapping
• silently coerce ambiguous string values like "null" to null
• convert arbitrary prose into JSON
• act as a general ETL or schema platform

Usage

Python

from structured_output_cleaner import clean_structured_output

result = clean_structured_output(
    'Sure — here is the JSON you asked for:\n{"count":"5","active":"true"}',
    schema={
        "properties": {
            "count": {"type": "number"},
            "active": {"type": "boolean"}
        },
        "required": ["count", "active"]
    }
)

CLI

$python -m structured_output_cleaner.cli '{status:"ok", count:"4",}'

Apify actor

This repo now includes an Apify-first wrapper:

• actor entrypoint: apify_main.py
• actor metadata: .actor/actor.json
• actor input schema: .actor/input_schema.json
• example payloads/results: apify_examples/

Apify input contract:

• rawInput (required string)
• schema (optional top-level schema object)
• fieldMappings (optional top-level string-to-string mapping object)

The actor preserves the current report contract by returning the same top-level result structure from clean_structured_output.

Response shape

• cleaned_output
• success
• issues_found
• fixes_applied
• unresolved_issues
• confidence_score
• repair_class_summary
• raw_input_excerpt

Trust note

High confidence is reserved for clean or narrowly repaired outputs with no unresolved trust issues. If duplicate keys, mapping collisions, or unresolved schema ambiguity remain, the tool downgrades confidence and does not present the result as a clean success.

Known limitations

See KNOWN_LIMITATIONS.md.

Apify notes

• Launch surface is Apify-first; CLI remains for local dev/testing.
• Schema support exposed in Apify is still lightweight and top-level only.
• The actor writes the result to the default dataset and to the OUTPUT key-value store record.
• MCP remains deferred.

Test

$python -m unittest discover -s tests -v