Metadata-Version: 2.4
Name: radio-city-director
Version: 0.5.0
Summary: Agent-ready RADIO CITY character semantics, visual discovery, world-bible canon, creator interviews, continuity, CLI, SDK, and optional MCP server.
Keywords: agents,anime,character-design,worldbuilding,canon,style-discovery,cli,sdk,mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"

# radio-city-director

`radio-city-director` is the shared semantic, visual-direction, discovery, and canon engine for **RADIO CITY / HIKAGO**. Version 0.3 adds a first-class **world bible** alongside the existing character router, visual style discovery, creator interviews, cast continuity, CLI, Python SDK, JSON agent tools, ChatGPT Skill, and optional MCP server.

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:

```bash
pip install radio-city-director
```

With MCP support:

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

From the local 0.3 wheel:

```bash
pip install dist/radio_city_director-0.3.0-py3-none-any.whl
```

## Compile for a model or agent

```bash
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:

```bash
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

Version 0.3 adds a structured canon model with separate **status** and **visibility** fields.

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

```bash
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:

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

Render model-ready context:

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

Check conflicts:

```bash
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:

```bash
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:

```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.

```bash
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:

```bash
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

```python
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

```bash
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

```python
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

```python
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

```bash
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

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
radio-city candidate-promote reviews.json back-city-001 \
  --reason creator_lock \
  --creator-verbatim "Lock this location into story continuity."
```

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.

```bash
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.
