Skills reference top-level flyte.File, flyte.Directory, flyte.DataFrame, and flyte.condition that don't exist in current flyte SDK (2.5.14)

[BadToast]

Summary

Nearly every SDK skill in this repo references top-level symbols on the flyte
module (flyte.File, flyte.Directory, flyte.DataFrame, flyte.condition)
that are not exported by the current flyte Python SDK. The real symbols
live under the flyte.io.* submodule (with a slight rename for Dir), and the
condition API has a different function name and return type entirely.

Verified against flyte==2.5.14 (PyPI, released 2026-07-23 — the latest
release as of filing). Also checked flyte==2.1.3 — same picture. The
top-level flyte package has never exported these names in the 2.x line as
far as I can tell.

Filing here rather than in flyteorg/flyte because the correct symbols
already exist in the SDK — the skills just point at the wrong path. But
happy to redirect if maintainers prefer to add top-level re-exports to the
SDK instead of updating the skill docs; see "Direction question" at the
bottom.

How to reproduce

python3 -m venv /tmp/flyte-check && source /tmp/flyte-check/bin/activate
pip install --quiet 'flyte==2.5.14'
python3 - <<'PY'
import flyte, flyte.io
print("flyte.File exists?     ", hasattr(flyte, "File"))
print("flyte.Directory exists?", hasattr(flyte, "Directory"))
print("flyte.DataFrame exists?", hasattr(flyte, "DataFrame"))
print("flyte.condition exists?", hasattr(flyte, "condition"))
print()
print("flyte.io.File exists?     ", hasattr(flyte.io, "File"))
print("flyte.io.Dir exists?      ", hasattr(flyte.io, "Dir"))
print("flyte.io.Directory exists?", hasattr(flyte.io, "Directory"))
print("flyte.io.DataFrame exists?", hasattr(flyte.io, "DataFrame"))
print()
print("flyte.new_condition exists?  ", hasattr(flyte, "new_condition"))
print("flyte.ConditionWebhook exists?", hasattr(flyte, "ConditionWebhook"))
PY

Output on my machine:

flyte.File exists?      False
flyte.Directory exists? False
flyte.DataFrame exists? False
flyte.condition exists? False

flyte.io.File exists?      True
flyte.io.Dir exists?       True
flyte.io.Directory exists? False
flyte.io.DataFrame exists? True

flyte.new_condition exists?   True
flyte.ConditionWebhook exists? True

Confirming against the wheel's own __all__ lists:

• flyte/__init__.py::__all__ — does not include File, Directory,
  DataFrame, or condition. It does include new_condition and
  ConditionWebhook.
• flyte/io/__init__.py::__all__ — ["PARQUET", "DataFrame", "Dir", "EmptyDir", "File", "HashFunction"].

Note the naming subtlety: it's flyte.io.Dir, not flyte.io.Directory. So
the "add .io." fix isn't a pure prefix substitution for Directory.

Discrepancies

Bug 1 — flyte.File (should be flyte.io.File)

Used across 9 of the 10 SDK skills. Selected line references:

• plugins/flyte/skills/flyte-sdk-author/SKILL.md — lines 47, 50, 53, 56,
  59, 79, 80, 261, 264, 268, 298, 309, 400, 401
• plugins/flyte/skills/flyte-sdk-types/SKILL.md — lines 34, 41, 43, 49, 50,
  54, 57, 58, 67, 70, 72, 123, 127, 188, 193, 229, 262, 266, 297, 302, 305,
  318, 325, 335, 340, 343, 363, 370, 375, 392, 395 (this is the primary
  types reference so it's the most affected)
• plugins/flyte/skills/flyte-sdk-ship/SKILL.md — line 280
• plugins/flyte/skills/flyte-sdk-run/SKILL.md — lines 340, 347, 349
• plugins/flyte/skills/flyte-sdk-optimize/SKILL.md — lines 39, 47, 51, 55,
  72, 81, 111, 232
• plugins/flyte/skills/flyte-sdk-eval/SKILL.md — lines 48, 149, 156, 251,
  284, 295, 424
• plugins/flyte/skills/flyte-sdk-data/SKILL.md — lines 87, 93, 96, 106,
  112, 115, 122, 125, 351, 358, 361, 368, 393, 398, 449, 452, 453, 454, 455
• plugins/flyte/skills/flyte-sdk-ml/SKILL.md — 20+ references throughout
• plugins/flyte/skills/flyte-sdk-agent/SKILL.md — line 506

Also: every skill's "Grounding References" preamble (line ~22 of each)
literally recommends searching upstream for flyte.File as an example
symbol — since flyte-docs search is literal-substring, that guidance
returns nothing useful with the current SDK.

Suggested fix: substitute flyte.File → flyte.io.File throughout,
including the preamble example.

Bug 2 — flyte.Directory (should be flyte.io.Dir)

• plugins/flyte/skills/flyte-sdk-types/SKILL.md — lines 35, 77, 79, 85, 94,
  364, 372, 375
• plugins/flyte/skills/flyte-sdk-author/SKILL.md — line 401

Suggested fix: substitute flyte.Directory → flyte.io.Dir (not
flyte.io.Directory — that path does not exist).

Bug 3 — flyte.DataFrame (should be flyte.io.DataFrame)

Used across 6 SDK skills. Selected line references:

• plugins/flyte/skills/flyte-sdk-types/SKILL.md — lines 36, 101, 109, 113,
  116, 120, 123, 130, 143, 146, 147, 158, 161, 193, 343, 347, 365, 371
• plugins/flyte/skills/flyte-sdk-optimize/SKILL.md — lines 63, 103, 127
• plugins/flyte/skills/flyte-sdk-ml/SKILL.md — lines 100, 101, 358, 387,
  571, 572, 599, 600, 601, 630, 631
• plugins/flyte/skills/flyte-sdk-eval/SKILL.md — lines 41, 111, 114, 122,
  128, 129, 179, 202, 235, 300, 315
• plugins/flyte/skills/flyte-sdk-data/SKILL.md — lines 39, 48, 51, 62, 65,
  152, 157, 166, 170, 173, 221, 246, 264, 285, 313, 384, 393, 398, 403, 448
• plugins/flyte/skills/flyte-sdk-author/SKILL.md — lines 238, 243, 248,
  258, 259, 269, 303, 323, 401

Suggested fix: substitute flyte.DataFrame → flyte.io.DataFrame
throughout.

Bug 4 — flyte.condition("name", ...) (wrong shape entirely)

Only two references, but the first one is a full working-looking code example
that misleads readers on the actual API.

• plugins/flyte/skills/flyte-sdk-author/SKILL.md, lines 124–133:

  @env.task
  async def main() -> None:
      result = await flyte.condition(
          "human-approval",
          description="Wait for human approval before proceeding",
          timeout="24h",
      )
      if result.approved:
          await deploy_pipeline()
      else:
          await notify_rejected()

• plugins/flyte/skills/flyte-sdk-agent/SKILL.md, line 244 — a routing table
  that references flyte.condition for external gates.

In flyte==2.5.14 the current API is:

• flyte.new_condition(...) (not flyte.condition(...)) — returns a
  flyte.ConditionWebhook.
• The return object doesn't appear to expose a .approved attribute; the
  webhook contract is different. I haven't traced the full new API here
  because the correction is non-obvious, but citing so maintainers know
  the example needs a rewrite, not just a rename.

Suggested fix: replace the example with one built against the actual
new_condition / ConditionWebhook API — likely by adapting from the SDK
tests or examples in flyteorg/flyte or unionai-examples.

Impact

Skills are read by AI agents (Claude Code, Codex, Cursor, Windsurf, opencode,
pi, Hermes) which then generate code following the exact patterns shown. So
these aren't just doc bugs — they actively produce non-compiling user code.
Anyone using the marketplace today gets NameError: module 'flyte' has no attribute 'File' on their first generated pipeline.

Direction question

Two possible fixes, and this is a decision for the maintainers rather than
something I want to unilaterally PR:

1. Update the skills to use the current flyte.io.* and new_condition
   spellings. Cheapest change; docs-only; matches what actually exists today.
2. Add top-level re-exports in the flyte SDK so flyte.File,
   flyte.Directory, flyte.DataFrame, and flyte.condition all resolve.
   Larger change touching another repo; makes the skills right retroactively
   but also expands the SDK's public API surface.

Happy to open a PR against this repo for (1) if that's the preferred
direction — the File / Directory / DataFrame substitutions are mechanical.
The condition example would need input from someone closer to the
new_condition API on what the idiomatic v2.5.14 example should look like.

Environment

• OS: macOS 25.5.0
• Python: 3.12
• flyte: 2.5.14 (also verified 2.1.3 — same discrepancies)
• Reproducer above is standalone; no cluster login needed.

PS — same three flyte.* shorthand mentions in the current docs (much smaller scope)

While confirming the SDK behavior I also grep'd the current
llms-full.txt files that this repo's flyte-docs MCP server searches.
The docs are ~99.99% correct — 400+ code examples across both sites use
flyte.io.* — but there are two unique narrative lines that use the
same wrong shorthand as the skills. Mentioning here rather than in a
separate issue since the scope is trivial and same-org routing seems
easier.

Verified against https://www.union.ai/docs/v2/flyte/llms-full.txt and
https://www.union.ai/docs/v2/union/llms-full.txt, both fetched
2026-07-27:

1. "Type hints are required" section (Quick Start / getting-started
   area — flyte line 596, union line 639):

   Supported types include:
   …

   • Files: flyte.File, flyte.Directory

   Should read flyte.io.File, flyte.io.Dir.

2. "Inline I/O threshold" section (Task Programming — flyte line 5689,
   union line 6369):

   This setting does not affect flyte.io.File, flyte.io.Dir,
   or flyte.DataFrame,

   The flyte.io.File/Dir link is correct; the flyte.DataFrame
   markdown link in the very next clause should be flyte.io.DataFrame.

Counts across both sites for reference:

Symbol	Flyte docs	Union docs
flyte.io.File (correct)	104	112
flyte.io.Dir (correct)	170	421
flyte.io.DataFrame (correct)	66	71
flyte.new_condition (correct)	10	10
flyte.File (wrong)	1	1
flyte.Directory (wrong)	1	1
flyte.DataFrame (wrong)	1	1
flyte.condition (wrong)	0	0

Notably flyte.condition appears zero times in either docs site —
the condition example bug is skill-repo-only; the docs get that API
right (new_condition + ConditionWebhook).

Happy for this to be split into a separate docs issue if that fits your
workflow better — just flagging here to save someone the grep.

[cosmicBboy]

Thanks for the exceptionally thorough report — the reproducer and line references made this fast. Opened #27 taking direction (1) (fix the skills).

Two things worth calling out beyond the mechanical substitutions:

1. import flyte alone doesn't expose flyte.io. So the pure flyte.File → flyte.io.File substring fix isn't sufficient on its own — a runnable example with import flyte + flyte.io.File still throws AttributeError: module 'flyte' has no attribute 'io'. The PR also adds import flyte.io to every runnable example block that needed it (21 blocks), matching how the docs import it.

2. flyte.condition example is rewritten against the real API (pulled from the SDK's own _condition.py docstring), not just renamed:

   condition = await flyte.new_condition(name, prompt=..., data_type=bool, timeout=timedelta(hours=24))
   approved = await condition.wait()

   You were right that .approved wasn't the contract — wait() returns the typed payload (bool here).

Also confirmed your flyte.io.Dir (not flyte.io.Directory) catch — used Dir throughout.

The PS docs-site lines (llms-full.txt) are in other repos, so out of scope for this PR; leaving that to a docs issue if you'd like to file one.