Enrich a raw TCGPlayer Lorcana CSV export with full card data.

Fetches card data from LorcanaJSON and lorcana-api.com and adds Ink color, Ink Cost, Card Type, Subtypes, Strength, Willpower, Lore Points, Inkable, Keywords, and Abilities to each row.

Writes two output files next to the input: enriched_{filename} — enriched collection CSV dreamborn_{filename} — import-ready CSV for dreamborn.ink

Args: input_path: Absolute path to the raw TCGPlayer CSV export. cache_path: Optional path to a previous enriched CSV to speed up re-runs by skipping API calls for cards already seen. refresh_prices: If True, overwrite each row's TCG Market Price with a live tcgcsv.com lookup for that exact printing, instead of leaving whatever the raw TCGPlayer export had at download time. Use this to bring an old enriched CSV's prices current without re-exporting from TCGPlayer.

Look up a Lorcana card by name and return its full stats, abilities, and legality.

Searches LorcanaJSON for an exact name match, then falls back to partial match. Supplements with duels.ink data for format legality, structured abilities, and card image URL. If the same card exists in multiple sets, the most recent printing is returned unless set_name is specified.

Args: name: Card name, e.g. "Mirage - Super Recruiter" or just "Mirage". set_name: Optional set name to narrow the search, e.g. "Wilds Unknown".

Resolve an informal, misspelled, or subtitle-less card name to specific card(s).

Unlike lookup_card's simple substring match, this tokenizes the query and scores it against every card's name and subtitle, tolerating missing dashes ("goofy musketeer"), missing subtitles ("Elsa" — which returns all her versions), word order, and minor typos ("musketer"). Use this when lookup_card fails or when you're not sure of a card's exact printed name.

Returns one of three shapes:

• A single confident match: full card detail (same as lookup_card).

• Multiple plausible matches: a ranked top-3 list with confidence scores, for you to disambiguate (e.g. "Pete" with no further qualifier, or a bare character name matching several printings).

• No match: nothing scored above the noise floor.

Args: name: Informal, partial, or misspelled card name. set_name: Optional set name to narrow the search, e.g. "Wilds Unknown".

Search the full Lorcana card pool by any combination of filters.

All filters are optional and ANDed together, except colors: a card matches if it has ANY of the given colors, so dual-ink cards surface for either half.

Args: colors: Comma-separated ink color(s), e.g. "Amber,Steel". Case-insensitive. card_type: "Character", "Action", "Item", "Location", or "Song" (Action cards with the Song subtype). rarity: "Common", "Uncommon", "Rare", "Super Rare", "Legendary", "Enchanted", "Epic", "Iconic", or "Special". set_name: Set name substring, e.g. "Wilds Unknown". cost_min: Minimum ink cost, inclusive. Pass -1 (default) for no minimum. cost_max: Maximum ink cost, inclusive. Pass -1 (default) for no maximum. keyword: Keyword ability name, e.g. "Evasive", "Rush", "Bodyguard", "Shift". ability_text: Substring to search for in full ability text (case-insensitive). subtype: Subtype/classification, e.g. "Toy", "Hero", "Villain", "Princess". offset: Pagination offset, 0-based. limit: Max results in this page (default 25, capped at 200).

Find every Character that can sing a given song, for free-song Singer combos.

A character can sing a song if its printed ink cost meets the song's cost outright, OR it has a "Singer X" keyword with X meeting the song's cost — Singer lets a cheap character punch above its actual cost for singing purposes only (see the Steelsong package: Amber Singers unlocking expensive Steel songs for free). Provide either song_name (resolved the same fuzzy way as resolve_card) or a raw cost threshold — not both.

Results are grouped: Singer-keyword characters first (the actual "discount" picks — highest Singer value, then cheapest actual cost), followed by characters that simply cost enough to sing it outright, cheapest first.

Args: song_name: Name of a Song card, e.g. "Be Our Guest". Fuzzy-matched. cost: Raw song cost threshold to use instead of song_name, e.g. 5. colors: Optional comma-separated ink color(s) to restrict characters to, e.g. "Amber,Steel". collection_csv: Optional path to an enriched collection CSV — when given, each character is flagged with how many copies you own. limit: Max characters to list (default 50, capped at 200).

Filter an enriched collection CSV to cards legal in a specific play format.

Legality data comes from duels.ink, which tracks Core EN, Infinity, Core ZH, and Core JA rotation. Poorcana (Common/Uncommon only, 50-card min) is derived from the Rarity column in the CSV — no external lookup needed.

Args: csv_path: Absolute path to an enriched Lorcana collection CSV. format: "core", "infinity", "core_zh", "core_ja", or "poorcana".

Audit an enriched Lorcana collection CSV against live API data.

Checks Ink color, Ink Cost, Card Type, Subtypes, Inkable, and stats (Strength / Willpower / Lore Points) for every non-promo card. Useful after a new set releases or if enrichment data looks suspicious.

Args: csv_path: Absolute path to an enriched Lorcana collection CSV.

Analyze a raw deck list and return curve, composition, and legality stats.

Accepts one card per line, e.g. "4x Goofy - Musketeer" or "4 Goofy - Musketeer" (both "4x" and "4 " are accepted; qty is optional and defaults to 1). Lines starting with "#" or "//" are treated as comments and skipped.

Reports: ink curve (1-2/3-4/5-6/7+ cost brackets), inkable vs. uninkable count, color split, card type split, an estimated lore-per-turn (sum of Character lore values), a Core Constructed legality check (60-card minimum, max 4 copies of any card, at most 2 ink colors), and any card names that couldn't be resolved.

Args: deck_list: Raw deck list text, one card per line.

Compare a deck list against your collection: what you own, what's missing, and the estimated cost to complete it.

Cross-references a raw deck list (same format as analyze_deck: 4x Card Name per line) against an enriched collection CSV. For every card you're short on, first checks the CSV's own TCG Market Price (you already own at least one printing, so it's already there — no network needed). Only cards you own zero copies of fall back to a live TCGPlayer lookup via tcgcsv.com (cheapest printing across all sets/rarities — gameplay is identical regardless of rarity or art). That fallback fetch only happens if at least one card actually needs it, and its price data is cached 24h.

Args: deck_list: Raw deck list text, one card per line (e.g. "4x Goofy - Musketeer"). collection_csv: Absolute path to an enriched Lorcana collection CSV.

Automatically assemble a legal, curve-balanced ~60-card decklist for an ink pair and format, in one of 3 modes:

• "collection": build only from cards you own (capped at owned quantity per card). If fewer than 60 legal owned cards exist, reports the shortfall honestly instead of padding with irrelevant fillers.

• "ideal": build the best deck regardless of ownership. If collection_csv is given, also shows what you already own, what's missing, and the price to complete it (via tcgcsv.com).

• "market": build the best deck ignoring any collection, and prices every card in it (not just the gap) via tcgcsv.com.

This is a heuristic curve/keyword-value builder — it optimizes ink curve, stat efficiency, and keyword value, not multi-card combos or synergy packages. See the disclaimer at the bottom of every result.

Args: ink_colors: Comma-separated ink color(s), e.g. "Amber,Sapphire". 1-2 colors for core/core_zh/core_ja/poorcana, 1-6 for infinity. mode: "collection", "ideal", or "market". format: "core", "infinity", "core_zh", "core_ja", or "poorcana". collection_csv: Absolute path to an enriched collection CSV. Required for mode="collection"; optional for "ideal"; ignored for "market". rotation_safe: If True and format="core", restrict to the rotation group that will still be legal after the next rotation event. No-op (with a note) for other formats.