Poetry to Image

Turn Chinese poetry into a coherent visual concept and a generated image. The deterministic scripts use only the Python standard library; Codex supplies the semantic judgment and final prompt refinement.

Fixed locations

Keep source code and user data separate:

• This skill: the directory containing this SKILL.md, normally $HOME/.agents/skills/poetry-to-image/.
• Private configuration: $HOME/poetry-to-image/.env.
• Generated works: $HOME/poetry-to-image/outputs/<run-id>/.

Honor POETRY_TO_IMAGE_HOME when it is already set. Never store credentials or generated works inside the installed skill directory.

Before running

1. Resolve the absolute skill directory from this SKILL.md; do not assume the current working directory is the skill directory.
2. Select a local Python 3.10+ command: prefer python3, then py -3 on Windows, then python.
3. If Codex requests permission, ask only for:
   - network access to https://poetry-api.1token-store.com and https://edge.1token-store.com;
   - read/write access to $HOME/poetry-to-image/.
4. Do not ask the user to enable Full access. If a managed policy blocks the home directory, ask the user to attach or open $HOME/poetry-to-image/ as a local folder instead.

Secret configuration

Check configuration with:

<PYTHON> <SKILL_DIR>/scripts/config_manager.py show

If api_key is empty:

1. Tell the user to apply for a dedicated, revocable key at https://1token-store.com/keys.
2. Ask the user to send it in the current private conversation.
3. Do not quote, summarize, log, or repeat the key.
4. Start this command without putting the key in the command line:

<PYTHON> <SKILL_DIR>/scripts/config_manager.py configure --key-stdin

5. Send the key only through the host's process-stdin facility. Never interpolate it into a shell command, filename, prompt, JSON output, or image metadata.
6. Run config_manager.py show and confirm only [REDACTED] is displayed. On Unix, verify .env mode is 0600; the script applies it automatically.
7. Suggest that the user delete their key-bearing chat message after configuration. Do not require them to edit .env manually.

The default service settings are:

• Poetry API: https://poetry-api.1token-store.com
• Image API: https://edge.1token-store.com
• Image model: gpt-image-2

Default workflow

1. Select a poem and prepare a run

For a theme, line, title, or author:

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py prepare --query "<USER_QUERY>"

For a random complete poem:

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py prepare

The search script expands classical imagery, queries multiple terms, merges and deduplicates results, probes exact titles, locally reranks candidates, and rejects fragments. Never replace this with “take the first API result.”

Read the returned poem_path and draft_prompt_path.

2. Refine the final prompt

Use the draft as a strong starting point. Preserve:

• the exact poem and author; preserve dynasty only as upstream source metadata, and do not use an unverified dynasty value to force period-specific clothing or architecture;
• concrete imagery and season/time clues;
• one coherent scene rather than an inventory of objects;
• clear foreground, middle ground, background, light, atmosphere, material, and palette;
• the selected original style's medium and composition;
• low-text or no-text output, with no watermark, logo, QR code, brand, or real celebrity.

Apply the user's requested style, mood, subject emphasis, and aspect ratio. Save the refined prompt as <run_dir>/prompt.txt. Do not silently replace the poem with a more famous one after the user has approved it.

3. Configure the key if needed

If needs_image_key is true, complete Secret configuration before generation.

4. Generate and display

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py generate --run-dir "<RUN_DIR>"

The command uses prompt.txt when present, otherwise draft_prompt.txt. If the run already contains a verified generated image, it returns that image without calling the provider again. Use --force only when the user explicitly asks to regenerate the same run and accepts another billable request. After success:

1. Verify image_path exists and is a parseable PNG, JPEG, or WebP. Record its actual pixel dimensions. Never discard or fail a valid paid image because its ratio differs from the requested aspect.
2. Display or attach the local image directly in the conversation. If aspect_mismatch is true, mention the provider-returned dimensions as a non-blocking note.
3. Give the poem title, author, selected style, aspect ratio, and run directory.
4. Do not upload to IMA or any other archive unless the user separately asks for one.

Focused modes

Search only

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py search "<QUERY>" --limit 5

Return ranked poems with match reasons. Do not generate an image.

Random poem only

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py random

Return the normalized poem. Do not generate an image.

Prompt only

Run prepare, refine the draft, save prompt.txt, and return the poem plus prompt. Do not request an image key when the user does not want image generation.

User-provided poem

Normalize the poem to a UTF-8 JSON file containing title, author, dynasty, and a lines array, then run:

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py prepare --poem-file "<POEM_JSON>"

Use source: "user-provided" when no public source is known.

Reuse the previous poem

Use the previous run's poem.json to create a new run without changing the old output:

<PYTHON> <SKILL_DIR>/scripts/poetry_to_image.py prepare --poem-file "<PREVIOUS_RUN>/poem.json" --style "<STYLE>" --aspect <landscape|portrait|square>

Then refine and generate normally. Never overwrite the previous image or metadata.

Output contract

Each successful run is self-contained:

$HOME/poetry-to-image/outputs/<run-id>/
├── image.png | image.jpg | image.webp
├── poem.json
├── poem.md
├── analysis.json
├── draft_prompt.txt
├── prompt.txt
└── metadata.json

metadata.json may contain provider base URL, model, size, and local paths. It must never contain the API key, Authorization header, raw secret-bearing requests, or hidden Codex instructions.

When the user asks to package or share results, package only the selected run directory or outputs/; never package the parent $HOME/poetry-to-image/ because it contains .env.

Error handling

• Poetry API unavailable: report the endpoint and error; do not invent a poem or API response.
• No quality search result: broaden terms once, show candidates, and ask the user to choose if still ambiguous.
• Missing key: follow Secret configuration.
• HTTP 401/403: say the key is invalid or unauthorized without displaying it.
• HTTP 402/quota error: tell the user to check balance or key limits.
• HTTP 429: wait briefly and retry once; do not loop.
• HTTP 5xx/network timeout: retry once, preserve the prepared run, and report the blocker.
• Invalid image bytes: do not save them with an image extension and do not claim generation succeeded.

References

Read only when needed:

• references/poetry-api.md — endpoint and response contract.
• references/security-and-storage.md — sandbox, secret, and sharing rules.
• assets/prompt-styles.json — original compact visual-style library.
• assets/motif-lexicon.json — imagery extraction rules.