radio-city-director

radio-city-director is the shared semantic, visual-direction, discovery, and canon engine for RADIO CITY / HIKAGO. Version 0.6.1 is the current public release: character routing, visual discovery, world bible, reference-bound rendering, R&D candidate lifecycle, cinematic-elastic location maps, and skyline masks. Public-only canon is a complete projection, and the final image gate rechecks files instead of trusting stored materialization flags.

The package keeps four concerns separate but interoperable:

1. adult character semantics,
2. diverse but strictly nonsexual minor character semantics,
3. RADIO CITY visual grammar and reference-image style discovery,
4. HIKAGO / RADIO CITY structured canon, uncertainty, and creator interviews.

Body shape is never treated as an age signal. Provisional or creator-undecided lore is never silently promoted into confirmed canon.

Install

After publishing to PyPI:

pip install radio-city-director

With MCP support:

pip install 'radio-city-director[mcp]'

Pin a reviewed wheel with pip's hash-checking mode when evaluating a specific release. Historical 0.3 local-wheel install instructions are obsolete; install from PyPI.

Compile for a model or agent

radio-city compile \
  --age 32 \
  --intent edit \
  --text "reduce bust volume while preserving identity" \
  --role "experienced attorney" \
  --style "RADIO CITY house style"

Agent-friendly JSON:

radio-city compile --stdin-json --json <<'JSON'
{
  "age": 15,
  "intent": "create",
  "text": "design a distinct debate club student",
  "role": "debate club student",
  "build": "tall and wiry",
  "setting": "school hallway"
}
JSON

Use --strict when unattended agents should receive meaningful exit codes for non-allow semantic routes. The result includes stable policy evidence with rule IDs and source fields.

HIKAGO / RADIO CITY world bible

The world bible keeps status and visibility separate. Public-only context and --public-only search omit hidden/creator-only entities, aliases, notes, interview answers, and creator notes. Unclassified interview material is creator-only by default.

Statuses:

• confirmed
• provisional
• creator_undecided
• contradicted
• deprecated

Visibility:

• public
• hidden
• rumor
• creator_only

This makes it possible to distinguish facts like "ordinary inhabitants believe they live on an island" from hidden creator truth about HIKAGO without collapsing them into one omniscient lore dump.

Seed the current canon

radio-city canon seed --out hikago_canon.json

The shipped starter seed currently captures the creator-confirmed material discovered in conversation, including:

• HIKAGO as the hidden colony-world / Ultra Zone 89,
• Radio City as its primary island-metropolis center,
• inhabitants not knowing the colony truth,
• the Chicago/Japan-inspired public-world model,
• the broad social-satire and post-band/streaming themes,
• the hybrid school/college/office institution,
• Varese as a working protagonist name with Verise retained as an unresolved spelling alias,
• the Back City record-bin naming origin,
• Captain Magus as the creator-performed in-universe persona whose precise narrative role is still creator-undecided.

Search it:

radio-city canon search hikago_canon.json streaming
radio-city canon search hikago_canon.json streaming --public-only
radio-city canon get hikago_canon.json captain-magus-function
radio-city canon list hikago_canon.json --status creator_undecided

Render model-ready context:

radio-city canon context hikago_canon.json
radio-city canon context hikago_canon.json --public-only

Check conflicts:

radio-city canon lint hikago_canon.json --strict

Worldbuilding interview

The canon layer has its own adaptive creator interview rather than overloading visual-style questions:

radio-city canon questions hikago_canon.json --count 3
radio-city canon answer hikago_canon.json \
  --question-id back-city \
  --answer "..."
radio-city canon interview hikago_canon.json --max-questions 6

Questions cover public belief versus hidden truth, everyday life, satire, geography, institutions, the music economy, genre neighborhoods, protagonist baseline, Captain Magus, Back City, naming culture, clue leakage, and mysteries that must remain deliberately unresolved.

Python:

from radio_city_director import CanonInterview, seed_hikago_bible

bible = seed_hikago_bible()
interview = CanonInterview(bible)
q = interview.next()[0]
print(q.prompt)
interview.answer(q.id, "creator answer")
print(interview.context())

Discover the RADIO CITY vibe from images

Visual discovery remains a separate workflow. A multimodal model inspects images; this deterministic package stores observations, asks creator questions, and synthesizes an executable style profile.

radio-city discover init --name "RADIO CITY visual bible" --out discovery.json
radio-city discover add-image discovery.json ./reference.png --reference-role exploratory
radio-city discover image-packet discovery.json img-001

After a vision-capable agent produces the structured observation:

radio-city discover observe discovery.json img-001 --observation-file observation.json
radio-city discover questions discovery.json --count 3
radio-city discover interview discovery.json
radio-city discover synthesize discovery.json --out radio_city_discovered.json --json

Reference roles are canonical, positive, exploratory, and anti. Anti-references contribute avoidance rules rather than being averaged into the desired look.

The distribution ships two useful calibration files:

• profiles/radio_city.json — the current provisional executable house profile,
• profiles/radio_city_starter_discovery.json — hashes/metadata for the first ten creator-supplied reference images plus the first creator vibe answers, intentionally leaving per-image classification open for continued calibration.

The current default style profile already reflects the first discovery pass: melancholy sacred-industrial atmosphere, noir/gothic/romantic theatricality, retro-futurist machines, quiet liminal spaces, monumental engineered architecture, and tensions such as beautiful ↔ empty, hyperconnected ↔ profoundly isolated, and culture everywhere ↔ nowhere affordable to make culture.

Discovery SDK

from radio_city_director import DiscoverySession, DiscoveryInterview, VisualObservation, synthesize_profile

session = DiscoverySession.new("RADIO CITY visual bible")
interview = DiscoveryInterview(session)
print(interview.next(3))

# A multimodal agent supplies image observations.
observation = VisualObservation(
    first_impression="elegant, nocturnal, slightly tired",
    vibe_words=["melancholy", "sacred-industrial", "theatrical"],
    confidence=0.8,
)

profile, summary = synthesize_profile(session)
print(summary)

Cast continuity and visual fingerprints

radio-city cast init --out cast.json
radio-city cast add cast.json --id akari --name Akari --age 29 --role attorney --fingerprint-file akari.json
radio-city cast lint cast.json --threshold 0.62
radio-city cast lock cast.json akari --fields face,silhouette,hair,fashion

Fingerprints cover face, silhouette, hair, posture, fashion, palette, acting, accessories, and movement so agents can detect same-face/body drift across an ensemble.

Python compile SDK

from radio_city_director import CharacterRequest, RadioCityDirector

result = RadioCityDirector().compile(CharacterRequest(
    age=32,
    intent="prompt",
    text="adult defense attorney on courthouse steps",
    role="defense attorney",
    setting="courthouse steps at dusk",
    mood="cool, exhausted confidence",
))

print(result.brief)
print(result.evidence)

Agent tools

from radio_city_director.agent import (
    tool_schema,
    discovery_tool_schemas,
    canon_tool_schemas,
    run_tool,
    run_discovery_tool,
    run_canon_tool,
)

The canon agent tools support next-question selection, answer storage, search, model-context rendering, and conflict linting. Discovery tools support multimodal observation packets and style synthesis.

MCP

pip install 'radio-city-director[mcp]'
radio-city mcp

The optional MCP stdio server exposes compile, schemas, style profile, discovery tools, and world-bible canon tools.

Semantic routing

The character compiler returns:

• allow
• redirect_safe
• needs_adult_age
• needs_separation

These are RADIO CITY semantic routes, not replacements for the host model's broader safety rules.

Useful commands

radio-city --version
radio-city doctor
radio-city schema
radio-city tool-schema
radio-city profile
radio-city mcp-capabilities
radio-city canon seed --out hikago_canon.json
radio-city canon context hikago_canon.json
radio-city discover status discovery.json
radio-city cast list cast.json

ChatGPT Skill

The repository output includes chatgpt/skill.zip. The skill vendors the same Python package source, so ChatGPT can use the deterministic compiler, visual discovery state, cast continuity, and world-bible canon without the PyPI package already being installed.

Reference-bound rendering (0.4)

Named recurring characters should be resolved before image generation. Register approved visual references in the cast registry, then build a render plan:

radio-city refs add cast.json --character varese --id varese-001 --file ./varese.png --role canonical
radio-city image-plan cast.json --characters Varese,Jazz --scene "rooftop at dusk" --mode strict-canon --strict

canon and strict-canon block if a requested known character lacks a canonical reference. Local-file references are verified for existence and SHA-256 integrity when a hash is registered; external URIs are marked for host resolution. The returned plan is model-agnostic: an agent should materialize/supply every reference_images[].uri to its image generator. strict-canon also carries locked traits and requires explicit overrides for intentional changes.

Persist review decisions with candidate-feedback so accept/veto/partial feedback can drive later discovery and rendering. Provider-neutral agent schemas now expose the same reference add/list/promote, image-plan/validate, and feedback operations; the MCP server mirrors them for stdio agents.

The downloadable full project also contains a private reference_pack/ with the currently approved Varese, Jazz, Blues, Techno, Rock, and Funk sheets plus a portable cast registry. The public PyPI wheel/sdist intentionally do not bundle those artwork files; use your own private reference pack or registry with the installed SDK/CLI. Relative local URIs in a registry file are resolved relative to that registry file when loaded by the CLI.

Strict-canon render gate

strict-canon now has two phases: planning and materialization. A plan is not permission to call an image model. Before rendering, resolve every canonical character reference to an actual local image file, then run the final gate.

radio-city image-plan reference_pack/radio_city_cast.json \
  --characters Varese \
  --scene "Varese entering Back City" \
  --mode strict-canon > plan.json

radio-city image-materialize plan.json \
  --out-dir ./render-inputs \
  --out materialized-plan.json \
  --strict

radio-city image-validate materialized-plan.json --strict

For connector/Drive/library refs, pass --bindings bindings.json, mapping a reference id or URI to the host-resolved local file. Only the returned image_inputs paths count as image-to-image conditioning. Fingerprints and prompt text never substitute for those bytes.

R&D-first image lifecycle

Generated images are R&D by default, even when strict-canon is used to preserve a named character's identity. Render continuity and story canon are separate concerns.

Store review using the creator's exact words plus an optional agreed score:

radio-city candidate-review reviews.json back-city-001 \
  --creator-verbatim "Looks fine to me. Back City is huge." \
  --score 7 \
  --tags "atmosphere,scale"

Assistant interpretation can be stored only as optional sidecar commentary. It is never authoritative over creator_verbatim.

Nothing becomes canon because it scored highly or was accepted during R&D. Canon requires an explicit promotion event:

radio-city candidate-promote reviews.json back-city-001 \
  --reason creator_lock \
  --creator-verbatim "Lock this location into story continuity." \
  --artifact-sha256 "<sha256 of the promoted image bytes>"

Valid promotion reasons are released, story_locked, and creator_lock.

Recursive additive image R&D

Image exploration is additive by default. Start with the smallest useful visual atom, generate, review, then add one coherent positive descriptor layer at a time. Earlier approved layers stay active recursively. Modification and removal are explicit later operations, and negative prompting is deferred until a concrete failure needs repair.

radio-city image-stack init --atom "Back City tower field" --out back-city-stack.json
radio-city image-stack add back-city-stack.json --descriptor "former major urban district"
radio-city image-stack add back-city-stack.json --descriptor "collapsed elevated highways"
radio-city image-stack packet back-city-stack.json
radio-city image-stack review back-city-stack.json back-city-002 --creator-verbatim "It is WIP. I want to explore the towers." --stage wip

Use image-stack revise only when the creator explicitly wants to modify or remove an earlier descriptor. Use image-stack repair for a specific observed failure; --negative is opt-in rather than the default.

Location continuity and skyline masks

0.6 adds a provider-neutral location continuity layer for places such as Back City. It is deliberately not a one-to-one world simulator: recurring silhouettes and selected landmarks can be strict while apparent spacing, scale, lens compression, secondary buildings, and camera distance remain cinematically elastic. Loaded maps are validated. Masks can include all anchors, strict anchors only, selected IDs, or none. Invalid location state is rejected independently of image-to-canon promotion.

Start a location map, attach an exploratory viewpoint, store a normalized skyline profile, and render a continuity mask:

radio-city location-map init --name "Back City" --width 2048 --height 1152 --out back-city-location.json
radio-city location-map viewpoint-add back-city-location.json --id candidate-4 --label "Candidate 4" --stage wip
radio-city location-map skyline-set back-city-location.json --viewpoint candidate-4 \
  --points "0,0.54;0.12,0.46;0.23,0.31;0.36,0.49;0.55,0.36;0.72,0.47;1,0.55" \
  --creator-verbatim "The skyline has too much in it, but this is definitely the direction I want for at least part of Back City." --stage wip
radio-city location-map anchor-add back-city-location.json --id sheared-tower-a --label "Sheared tower A" \
  --kind tower --polygon "0.18,0.24;0.25,0.22;0.27,0.66;0.19,0.67" --continuity strict --stage wip
radio-city location-map packet back-city-location.json --viewpoint candidate-4
radio-city location-map mask-render back-city-location.json --viewpoint candidate-4 --out back-city-preserve.png
radio-city location-map mask-render back-city-location.json --viewpoint candidate-4 --out back-city-strict.png --anchor-mode strict

The mask renderer is pure Python and writes an 8-bit grayscale PNG. preserve marks the city silhouette and selected anchor polygons in white; replace returns its inverse for inpainting/edit passes. --anchor-mode all|strict|selected|none chooses which landmarks are painted. Location-map stages remain rnd or wip; location continuity data does not promote an image to story canon. Agent/MCP users can call radio_city_location_mask_render instead of dropping to the CLI.

Host responsibilities remain in force: filesystem containment, human authorization, and the host model's safety rules. This package's semantic routes do not replace those rules. creator_verbatim records creator words; it is not an authentication credential.