Metadata-Version: 2.4
Name: fabric-notebook-toolkit
Version: 0.0.1a12
Summary: CLI tools for Microsoft Fabric Notebook — session management, code execution, Spark monitoring
Author: Microsoft Corporation
License: MICROSOFT SOFTWARE LICENSE TERMS
        FABRIC Notebook Toolkit (PREVIEW)
        
        April 2025
        IF YOU LIVE IN (OR ARE A BUSINESS WITH A PRINCIPAL PLACE OF BUSINESS IN) THE UNITED STATES, PLEASE READ THE “BINDING ARBITRATION AND CLASS ACTION WAIVER” SECTION BELOW. IT AFFECTS HOW DISPUTES ARE RESOLVED.
        These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS.
        1. INSTALLATION AND USE RIGHTS.
        a) General. You may install and use any number of copies of the software on your devices.
        b) Third Party Components. The software may include third party components with separate legal notices or governed by other agreements, as may be described in the ThirdPartyNotices file(s) accompanying the software.
        2. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to):
        a) work around any technical limitations in the software that only allow you to use it in certain ways;
        b) reverse engineer, decompile or disassemble the software, or otherwise attempt to derive the source code for the software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included in the software;
        c) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;
        d) use the software in any way that is against the law or to create or propagate malware; or
        e) share, publish, distribute, or lease the software, provide the software as a stand-alone offering for others to use, or transfer the software or this agreement to any third party.
        3. PRE-RELEASE SOFTWARE. The software is a pre-release version. It may not operate correctly. It may be different from the commercially released version.
        4. FEEDBACK. If you give feedback about the software to Microsoft, you give to Microsoft, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires Microsoft to license its software or documentation to third parties because Microsoft includes your feedback in them. These rights survive this agreement.
        5. DATA.
        a) Data Collection. The software may collect information about you and your use of the software, and send that to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may opt-out of many of these scenarios, but not all, as described in the product documentation.  There are also some features in the software that may enable you to collect data from users of your applications. If you use these features to enable data collection in your applications, you must comply with applicable law, including providing appropriate notices to users of your applications. You can learn more about data collection and use in the help documentation and the privacy statement at https://go.microsoft.com/fwlink/?linkid=521839. Your use of the software operates as your consent to these practices.
        b) Processing of Personal Data. To the extent Microsoft is a processor or subprocessor of personal data in connection with the software, Microsoft makes the commitments in the European Union General Data Protection Regulation Terms of the Microsoft Products and Services Data Protection Addendum to all customers effective May 25, 2018, at https://go.microsoft.com/fwlink/?linkid=2135030.
        6. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit https://aka.ms/exporting.
        7. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
        8. UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices.
        9. BINDING ARBITRATION AND CLASS ACTION WAIVER. This Section applies if you live in (or, if a business, your principal place of business is in) the United States.  If you and Microsoft have a dispute, you and Microsoft agree to try for 60 days to resolve it informally. If you and Microsoft can’t, you and Microsoft agree to binding individual arbitration before the American Arbitration Association under the Federal Arbitration Act (“FAA”), and not to sue in court in front of a judge or jury. Instead, a neutral arbitrator will decide. Class action lawsuits, class-wide arbitrations, private attorney-general actions, and any other proceeding where someone acts in a representative capacity are not allowed; nor is combining individual proceedings without the consent of all parties. The complete Arbitration Agreement contains more terms and is at https://aka.ms/arb-agreement-4. You and Microsoft agree to these terms.
        10. ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.
        11. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles, except that the FAA governs everything related to arbitration. If you acquired the software in any other country, its laws apply, except that the FAA governs everything related to arbitration. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court (excluding arbitration). If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court (excluding arbitration).
        12. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state, province, or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state, province, or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
        a) Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
        b) Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
        c) Germany and Austria.
        i.	Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
        ii.	Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
        Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.
        13. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
        14. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT OR INCIDENTAL DAMAGES.
        This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.
        It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.
        
        Please note: As this software is distributed in Canada, some of the clauses in this agreement are provided below in French.
        Remarque: Ce logiciel étant distribué au Canada, certaines des clauses dans ce contrat sont fournies ci-dessous en français.
        EXONÉRATION DE GARANTIE. Le logiciel visé par une licence est offert « tel quel ». Toute utilisation de ce logiciel est à votre seule risque et péril. Microsoft n’accorde aucune autre garantie expresse. Vous pouvez bénéficier de droits additionnels en vertu du droit local sur la protection des consommateurs, que ce contrat ne peut modifier. La ou elles sont permises par le droit locale, les garanties implicites de qualité marchande, d’adéquation à un usage particulier et d’absence de contrefaçon sont exclues.
        LIMITATION DES DOMMAGES-INTÉRÊTS ET EXCLUSION DE RESPONSABILITÉ POUR LES DOMMAGES. Vous pouvez obtenir de Microsoft et de ses fournisseurs une indemnisation en cas de dommages directs uniquement à hauteur de 5,00 $ US. Vous ne pouvez prétendre à aucune indemnisation pour les autres dommages, y compris les dommages spéciaux, indirects ou accessoires et pertes de bénéfices.
        Cette limitation concerne:
        •	tout ce qui est relié au logiciel, aux services ou au contenu (y compris le code) figurant sur des sites Internet tiers ou dans des programmes tiers; et
        •	les réclamations au titre de violation de contrat ou de garantie, ou au titre de responsabilité stricte, de négligence ou d’une autre faute dans la limite autorisée par la loi en vigueur.
        Elle s’applique également, même si Microsoft connaissait ou devrait connaître l’éventualité d’un tel dommage. Si votre pays n’autorise pas l’exclusion ou la limitation de responsabilité pour les dommages indirects, accessoires ou de quelque nature que ce soit, il se peut que la limitation ou l’exclusion ci-dessus ne s’appliquera pas à votre égard.
        EFFET JURIDIQUE. Le présent contrat décrit certains droits juridiques. Vous pourriez avoir d’autres droits prévus par les lois de votre pays. Le présent contrat ne modifie pas les droits que vous confèrent les lois de votre pays si celles-ci ne le permettent pas.
        
        
        
        
        DWT 28909257v1 0085000-001126
        
        
        
        
        
        
        DWT 28909257v1 0085000-001126
        
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
Requires-Dist: PyJWT[crypto]<3,>=2.9
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

Requires Python 3.10-3.13 and access to a Fabric workspace with an active
Spark-capable capacity.

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

## Quick Start

```bash
# Sign in to both Fabric CLI and Azure CLI with the same account and tenant.
# Azure CLI must be installed before running az login.
fab auth login --tenant <TENANT_ID>
az login --tenant <TENANT_ID>

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

# Start a session. Use data.session_id as <SID>.
fntk notebook start-session --workspace-id <WS_ID> --artifact-id <ART_ID> --json

# Repeat until data.livy_session_state is "idle".
fntk notebook get-session --workspace-id <WS_ID> --artifact-id <ART_ID> --session-id <SID> --json

# Submit code, then use the execution ID in the returned polling command as <EID>.
fntk code run --workspace-id <WS_ID> --artifact-id <ART_ID> --code "print('hello')" --json

# Repeat until data.status is "completed" or "error"; inspect data.outputs/data.error.
fntk code get-result --workspace-id <WS_ID> --artifact-id <ART_ID> --execution-id <EID> --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
```

Session startup can take several minutes. Follow `next_actions` for polling
intervals and retry limits; stop on query errors, terminal failures, or timeout.
Use `get-session` for the Livy session ID (`<LID>`) and `list-apps` for the Spark
application ID (`<APP>`).

## CLI Commands

```bash
fntk help              # Human-readable overview
fntk help --json       # Supported public commands, workflows and schemas
```

| Domain | Purpose |
|--------|---------|
| `discover` | Find workspaces, notebooks, lakehouses and capacity |
| `notebook` | Manage notebooks, sessions and lakehouse attachments |
| `code` | Submit code, retrieve results and request cancellation |
| `cell` | Read and edit notebook cells |
| `monitor` | Inspect Spark applications and diagnostics |
| `logs` | Download Spark and notebook logs |
| `resource` | Manage notebook resource files |
| `server` | Manage the local daemon |
| `init` | Install or update agent skills and plugins |
| `skill` | Inspect built-in skill content |

Use `fntk <domain> --help` for commands and options.

## Output Format

Most operational commands with `--json` return this envelope. Example session query:

```json
{
  "status": "success",
  "stage": "completed",
  "progress": 1.0,
  "message": "Session is idle",
  "data": {
    "session_id": "<SID>",
    "livy_session_state": "idle"
  },
  "next_actions": [],
  "plan_hints": [],
  "logs": [],
  "context": {"workspace_id": "<WS_ID>"},
  "error": null,
  "trace_id": "fntk-a1b2c3d4e5f6",
  "elapsed_ms": 234
}
```

Help and skill inspection use their own payloads. `notebook get-content
--output-file <FILE>` returns `status`/`file` and saves raw notebook JSON;
`notebook put-content --json` returns `status`/`message`. Ordinary
`notebook get-content --json` places notebook JSON in `data`.

Content-only edits retain cell types, attachments and existing metadata.
Explicit conversion to code removes that cell's attachments.

### 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 |

### Query success versus execution success

For `notebook get-session` and `code get-result`, top-level `status: "success"`
means the **query succeeded**, not that Spark is ready or the code succeeded.

| Field | Meaning |
|-------|---------|
| Top-level `status: "error"` | The command or query failed; inspect `error`. |
| `data.livy_session_state` | Wait for `"idle"` before submitting code. |
| `data.status` | Execution state: `"completed"` or `"error"` is terminal; keep polling nonterminal states. |
| `data.outputs` / `data.error` | Execution output and failure details. |

Exit code 0 alone does not guarantee successful Spark execution. Scripts and
agents must inspect the nested state.

## Runtime settings

Set environment variables before starting the CLI or daemon:

| Variable | Default | Description |
|----------|---------|-------------|
| `FNTK_LOG_LEVEL` | `INFO` | Console logging level |
| `FNTK_SERVER_PORT` | `19876` | Local daemon port |

## Auth

FNTK uses your current Fabric CLI identity. For notebook operations, install
Azure CLI and sign in to both CLIs with the **same account and tenant**, as shown
in Quick Start. An existing valid Azure CLI session can be reused. The `--tenant`
option selects a directory; omit it from both commands only if both CLIs already
use the intended tenant.

These are separate login flows, so first-time setup may require two interactive
sign-ins. FNTK attempts a Fabric CLI fallback when Azure CLI cannot provide the
additional token, but that fallback is not guaranteed. FNTK itself does not open
a login prompt. Use `fntk discover whoami --json` to check your identity; this
does not verify every permission needed for notebook operations.

## Local Daemon

`notebook start-session` automatically starts a local daemon for persistent
connections and asynchronous execution. Manual lifecycle management is optional:

```bash
fntk server start --json     # Start daemon on localhost (default port: 19876)
fntk server status --json    # Check status
fntk server stop --json      # Stop daemon
```

The daemon listens only on localhost. If an upgrade reports
`DAEMON_AUTH_UPGRADE_REQUIRED`, stop and restart it. Stopping the local daemon
does not cancel remote Spark jobs.

## Agent Skill Init

`fntk init` installs the bundled workflow skill and configures the external
Fabric Skills plugin for GitHub Copilot CLI (default), Codex or Claude Code.
The bundled skill is project-local by default; `--global` installs it in your
home directory. Interactive runs let you choose scope and skip plugin installation;
`-y` or JSON output skips prompts and uses defaults.

```bash
# Set up GitHub Copilot CLI
fntk init

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

# Install the bundled workflow skill globally
fntk init --global -y

# After upgrading FNTK, refresh installed skills/plugins
fntk init --update-skills -y
```

Use `--skip-fabric-skills` to skip the external plugin, or `fntk init --help`
for all options. If a host CLI is unavailable, init reports a warning and
completes the other setup steps.

Interactive terminal output uses color for headings, success, warnings, and errors. Set
`NO_COLOR=1` (or use redirected/JSON output) for plain text.

## For AI Agents

The [JSON manifest](#cli-commands) describes supported public commands,
workflows, output schemas and state transitions. Built-in guidance is available
without a repository checkout:

```bash
fntk skill list --json
fntk skill get pyspark --json
```

Integrations can identify the calling host with `--client-name github-copilot-cli`,
`--client-name claude-code` or `--client-name codex`. This is optional,
self-asserted telemetry metadata, not authorization; terminal users do not need
to configure it. Use `--client-attribution off` to disable attribution.

## Telemetry

By default, FNTK records logs and metrics locally and sends authorized remote
telemetry to Microsoft. Remote sending requires an authenticated notebook context;
startup events without one remain local. Collection is best-effort.

Set these environment variables **before starting the CLI or daemon**:

| Setting | Effect |
|---------|--------|
| `FNTK_TELEMETRY_RUNTIME=off` | Disable both local persistence and remote telemetry |
| `FNTK_TELEMETRY_DISABLED=1` | Disable remote telemetry only; keep local persistence |

Console output and CLI JSON remain available with either setting.
`fntk telemetry status --json` reports the running daemon's cached status, or
only the current CLI runtime if no daemon snapshot is available. It does not
start a daemon; missing telemetry does not establish whether a Spark job succeeded.
