fenic: Skill for Claude Code

fenic mechanics

fenic looks like PySpark and you already write its DataFrame surface well (select/filter/join/group_by/agg, semantic.extract/classify). This skill covers the mechanics that don't transfer — where fenic differs from PySpark/pandas intuition in ways that fail (often loudly, sometimes silently). For full signatures see reference/*.md (generated from the installed version); for the correction table and traps see gotchas.md.

Golden rule: after writing or editing a fenic pipeline, run fenic check <file> — a static lint (no execution) that resolves your fc.* symbols against the installed fenic and flags namespace/import mistakes (fenic.functions, fc.array vs fc.arr, fc.explode, …). Fix what it reports.

1. Import & namespace law (the #1 source of errors)

• Always import fenic as fc. Everything hangs off fc.. There is no fenic.functions (don't write from fenic import functions as F), no fenic.api.types, and no unified OpenAIModelConfig.
• Function namespaces: fc.text.*, fc.json.*, fc.markdown.*, fc.semantic.*, fc.embedding.*, fc.dt.*, and fc.arr.* for array ops. ⚠️ fc.array(...) is a constructor for array literals; the array-operations namespace is fc.arr (fc.arr.size, fc.arr.contains, fc.arr.sort, …).
• Flat on fc: free functions (fc.col, fc.lit, fc.when, fc.coalesce, fc.count, fc.sum, fc.avg, fc.collect_list, fc.struct, fc.udf, fc.async_udf, …), all types, and all model-config classes.
• explode / unnest are DataFrame methods, not functions: df.explode("col"), df.unnest("col") — never fc.explode(...).
• PySpark camelCase aliases (withColumn, groupBy, orderBy, dropDuplicates) do exist and work, but prefer snake_case.

2. Session & models

import fenic as fc
session = fc.Session.get_or_create(fc.SessionConfig(
    app_name="my_app",
    semantic=fc.SemanticConfig(
        language_models={"mini": fc.OpenAILanguageModel(model_name="gpt-4o-mini", rpm=500, tpm=200_000)},
        default_language_model="mini",
        # embeddings are a SEPARATE class + SEPARATE dict:
        embedding_models={"emb": fc.OpenAIEmbeddingModel(model_name="text-embedding-3-small", rpm=500, tpm=200_000)},
        default_embedding_model="emb",
    ),
))