Fabric Notebook Toolkit (fntk)

Agent Runtime Interface for Microsoft Fabric Notebooks — session management, code execution, Spark monitoring, all via CLI with structured JSON output.

Install

# Install the public alpha release
pip install fabric-notebook-toolkit==0.0.1a1

Quick Start

# Authenticate
fab auth login

# Set environment (persists to ~/.fntk/config.json)
fntk env set msit          # msit | prod | daily | dxt | edog

# Discover resources
fntk discover whoami --json
fntk discover list-workspaces --json
fntk discover list-notebooks --workspace-id <WS_ID> --json

# Start session + execute code
fntk notebook start-session --workspace-id <WS_ID> --artifact-id <ART_ID> --json
fntk code run --workspace-id <WS_ID> --artifact-id <ART_ID> --code "print('hello')" --json

# Monitor Spark
fntk monitor list-apps --workspace-id <WS_ID> --artifact-id <ART_ID> --livy-id <LID> --json
fntk monitor get-diagnostic --workspace-id <WS_ID> --artifact-id <ART_ID> --app-id <APP> --json

# Download logs
fntk logs get-driver --workspace-id <WS_ID> --artifact-id <ART_ID> --livy-id <LID> --app-id <APP> --json

CLI Commands (68 commands, 9 domains)

fntk help              # Human-readable overview
fntk help --json       # Machine-readable manifest (for agents)

Output Format

All commands with --json return a stable envelope:

{
  "status": "success",
  "stage": "completed",
  "progress": 1.0,
  "message": "Found 14 notebooks",
  "data": { ... },
  "next_actions": [
    {
      "type": "once",
      "command": "fntk notebook start-session --workspace-id <WS> --artifact-id <ART> --json",
      "description": "Start a session on a notebook"
    }
  ],
  "plan_hints": ["Start a session", "Execute code"],
  "logs": [],
  "context": {"workspace_id": "..."},
  "error": null,
  "trace_id": "fntk-a1b2c3d4e5f6",
  "elapsed_ms": 234
}

next_actions Types

Environment Configuration

Priority (highest to lowest):

1. FAB_API_ENDPOINT_FABRIC env var
2. ~/.fntk/config.json → default_env
3. Default: prod

fntk env set msit              # Persists to ~/.fntk/config.json
fntk env show --json           # Show current config with sources

If both env var and config.json are set and disagree, a warning is logged.

Feature Flags

Config file: ~/.fntk/config.json Env var override: FNTK_<FLAG_NAME> (e.g. FNTK_LOG_LEVEL=debug)

Auth

fab auth login     # Preferred (Fabric CLI MSAL cache)
az login           # Fallback

Local Daemon (optional)

For long-running WebSocket connections and async execution:

fntk server start --json     # Start daemon on 127.0.0.1:19876
fntk server status --json    # Check status
fntk server stop --json      # Stop daemon

The daemon uses per-user auth nonce (~/.fntk/server.<port>.auth), bound to localhost only.

Repository Init

fntk init bootstraps a git repo for agent workflows. It installs the bundled fabric-notebook-toolkit skill when missing, detects Fabric workspace folders from .platform files, resolves workspace/capacity IDs, and writes per-workspace agent instructions.

Generated instruction targets use native agent mechanisms:

• GitHub Copilot CLI: .github/instructions/*.instructions.md
• Codex: workspace-local AGENTS.md
• Claude Code: workspace-local CLAUDE.md

# Initialize the current git repo
fntk init

# Only scan one subtree for Fabric workspaces
fntk init fabric/yilintest2

# Initialize one explicit workspace folder
fntk init --workspace-folder fabric/yilintest2

# Non-interactive JSON mode with all enabled agent targets
fntk init --agent copilot codex claude -y --json

# After upgrading fntk, update installed skill and managed prompts
fntk init fabric/yilintest2 --update -y

Flags:

If an agent instruction file already exists, interactive runs ask before appending/updating the FNTK managed prompt block. Non-interactive runs skip existing files unless -y is set, and generated prompt content includes FNTK markers for future updates.

At the interactive workspace-name prompt, enter :i to ignore that workspace folder. Other input, including skip, is treated as a workspace name.

Upgrade flow: after installing a newer fntk, rerun fntk init [path] --update -y to refresh both installed skill content and managed prompt blocks.

Each invocation emits one aggregate init.summary metric, including the selected agent types, skill/instruction outcomes, completed stage, error code, and counts for detected, automatically resolved, user-renamed, explicitly ignored, and unresolved workspaces. The event does not include repository paths, workspace names or IDs, prompt input, or free-form error messages.

Bundled skill content remains inspectable with fntk skill list and fntk skill get <skill-id>.

For AI Agents

Agents can discover all capabilities via:

fntk help --json    # Returns full manifest: domains, commands, workflows, schemas

The manifest includes state machine definitions, output schema, and recommended workflows. See AGENTS.md for detailed agent integration guide.