Metadata-Version: 2.4
Name: fabric-notebook-toolkit
Version: 0.0.1a1
Summary: CLI tools for Microsoft Fabric Notebook — session management, code execution, Spark monitoring
Author: Microsoft Corporation
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: requests>=2.31.0
Requires-Dist: websockets>=12.0
Requires-Dist: ms-fabric-cli
Dynamic: license-file

# 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

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

## Quick Start

```bash
# 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)

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

| Domain | Commands | Description |
|--------|----------|-------------|
| `discover` | whoami, list-workspaces, list-notebooks, list-lakehouses, get-capacity, spark-settings | Resource discovery |
| `notebook` | create, delete, start-session, get-session, list-sessions, delete-session, restart-kernel, interrupt-kernel, set-lakehouse, get-lakehouse, list-livy-sessions | Notebook + session lifecycle |
| `code` | run, get-result, cancel, cancel-all, ping | Code execution |
| `cell` | list, get, update, append, insert, delete, get-output, set-language, set-parameter | Cell CRUD |
| `monitor` | list-apps, get-diagnostic, get-stages, get-progress, get-executors, get-environment, get-sql, get-resources, get-advice, ... (19 total) | Spark monitoring |
| `logs` | get-driver, get-executor, list-executors, get-livy, get-cell | Log download |
| `resource` | list, get, put, mkdir, delete, usage | Resource folder files |
| `server` | start, stop, status | Local daemon management |
| `env` | show, set | Environment configuration |
| `init` | `[path]` | Bootstrap repo agent instructions for Fabric workspaces |
| `skill` | list, get | Inspect built-in skill content |

## Output Format

All commands with `--json` return a stable envelope:

```json
{
  "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

| Type | Description | Fields |
|------|-------------|--------|
| `once` | Execute exactly once | command, description |
| `poll` | Retry until condition met | command, retry_after, max_retries, stop_condition |
| `conditional` | Execute if condition met | command, stop_condition |

## Environment Configuration

Priority (highest to lowest):
1. `FAB_API_ENDPOINT_FABRIC` env var
2. `~/.fntk/config.json` → `default_env`
3. Default: `prod`

```bash
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`)

| Flag | Default | Description |
|------|---------|-------------|
| `daemon_mode` | false | Route calls through HTTP daemon |
| `trace_enabled` | true | Include trace_id in responses |
| `log_level` | info | Logging verbosity |
| `default_env` | prod | Default environment |
| `server_port` | 19876 | Daemon port |
| `max_poll_retries` | 60 | Default poll retry count |
| `poll_interval` | 5 | Default poll interval (seconds) |

## Auth

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

## Local Daemon (optional)

For long-running WebSocket connections and async execution:

```bash
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`

```bash
# 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:

| Flag | Default | Description |
|------|---------|-------------|
| `[path]` | git root | Optional subtree to scan for Fabric workspace directories |
| `--workspace-folder PATH` | off | Explicit workspace folder to initialize; cannot be combined with `[path]` |
| `--agent NAME [NAME ...]` | GitHub Copilot CLI | Agent integrations to generate; enabled CLI values are `copilot codex claude` |
| `-g`, `--global` | off | Install missing bundled skill user-globally instead of under the git root |
| `-y`, `--yes` | off | Skip interactive prompts; use defaults |
| `--skip-skill-install` | off | Only generate workspace instructions |
| `--update` | off | Re-copy the bundled skill to existing install locations |
| `--output {text,json}` | `text` | Output format; JSON mode also skips prompts |

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:

```bash
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.
