Metadata-Version: 2.4
Name: nixtee-cli
Version: 0.9.7
Summary: GNN-based Neural Network Performance and hyperparameters Predictor
Home-page: https://github.com/ajandera/nixtee-cli
Author: Nixtee s.r.o
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: requests
Requires-Dist: torch
Requires-Dist: pyyaml
Requires-Dist: questionary
Requires-Dist: mcp
Requires-Dist: rich
Requires-Dist: pandas
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Nixtee CLI

Nixtee CLI is a GNN (Graph Neural Network)-based Neural Network performance and hyperparameter predictor. It provides an intelligent interface to design, analyze, optimize, and refine PyTorch neural network architectures.

---

## Table of Contents
1. [Key Features](#key-features)
2. [Architecture & Storage Locations](#architecture--storage-locations)
3. [Prerequisites](#prerequisites)
4. [Installation & Setup](#installation--setup)
   - [For Testers and Users (Quick Start)](#for-testers-and-users-quick-start)
   - [For Developers (Local Development)](#for-developers-local-development)
   - [Using Nix (Reproducible Dev Shell)](#using-nix-reproducible-dev-shell)
5. [Usage & CLI Commands](#usage--cli-commands)
   - [Interactive Chat Session Slash Commands](#interactive-chat-session-slash-commands)
6. [QA & Manual Testing Protocols](#qa--manual-testing-protocols)
   - [Test Case 1: Configuration & Credentials Storage](#test-case-1-configuration--credentials-storage)
   - [Test Case 2: Workspace Dataset Autodetection](#test-case-2-workspace-dataset-autodetection)
   - [Test Case 3: Interactive Design and Optimization Loop](#test-case-3-interactive-design-and-optimization-loop)
   - [Test Case 4: Security & Static AST Sanitization](#test-case-4-security--static-ast-sanitization)
   - [Test Case 5: Model Context Protocol (MCP) Server](#test-case-5-model-context-protocol-mcp-server)
7. [Development & Code Structure](#development--code-structure)
   - [Adding CLI Commands](#adding-cli-commands)
   - [Customizing the AST Security Engine](#customizing-the-ast-security-engine)
   - [Registering Custom MCP Tools](#registering-custom-mcp-tools)

---

## Key Features

- **Automated Performance Prediction:** Extract Graph representation of a PyTorch model and query the GNN SaaS backend for accuracy and latency estimations.
- **Intelligent Architecture Design:** Command-line AI assistant powered by local Ollama instances (specifically trained to generate valid, secure PyTorch models).
- **Automated Optimization Loop:** Iterative refinement of model designs (up to 20 attempts) to target >80% accuracy based on local dataset context.
- **Security-First AST Sanitization:** Static analysis blocks execution of dangerous statements (e.g. `os.system`, `subprocess`, `eval`) and enforces pure model definitions.
- **Model Context Protocol (MCP):** Start a built-in MCP server supporting stdio/SSE to integrate with external tools (e.g. Claude Desktop, cursor, or other agent frameworks).

---

## Architecture & Storage Locations

To aid development and debugging, be aware of the following system paths:
* **API Configuration File:** `~/.nixtee/credentials` (Stores API Key and Secret, generated via `/configure` or `nixtee configure`).
* **Chat History Storage:** `~/.nixtee/chat_history.json` (Maintains conversation context between sessions).
* **Workspace Output Directory:** `./nixtee_models/` (Where generated Python models and optimization checkpoints are stored).
* **Generated Target Model:** `./generated_model.py` (The final output containing the PyTorch class definition with injected hyperparameters and custom training launcher).

---

## Prerequisites

- **Python:** Version 3.10 or higher.
- **Ollama:** Nixtee uses Ollama locally to power its AI generation. If not already present, the CLI will automatically download and start the service (using `curl -fsSL https://ollama.com/install.sh`) and synchronize the `qwen2.5-coder:3b` intelligence module on its first run.

---

## Installation & Setup

Choose the setup method appropriate for your workflow:

### For Testers and Users (Quick Start)

Install the CLI globally or into your current Python environment:

```bash
pip install .
```

Alternatively, if you use [Nix](https://nixos.org/), run the CLI instantly without installing dependencies:

```bash
nix run github:ajandera/nixtee-cli
# or for local repository checks:
nix run
```

### For Developers (Local Development)

To modify or inspect the Nixtee CLI code, follow these steps to install in editable mode:

1. **Clone the repository:**
   ```bash
   git clone https://github.com/ajandera/nixtee-cli.git
   cd nixtee-cli
   ```

2. **Set up a Python Virtual Environment:**
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```

3. **Install in Editable Mode with Dependencies:**
   ```bash
   pip install -e .
   ```

4. **Verify Development Mode Setup:**
   Run `nixtee --help` or run the script directly:
   ```bash
   python nixtee_cli.py --help
   ```

### Using Nix (Reproducible Dev Shell)

If you have Nix installed, you can launch a reproducible dev shell containing Python 3.10 and all required packages (PyTorch, Pandas, Click, Questionary, MCP, Rich, and more) pre-configured:

```bash
nix develop
```
Inside this shell, run the script directly via:
```bash
python nixtee_cli.py --help
```

---

## Usage & CLI Commands

Once installed, use the following root commands:

* `nixtee` (or `python nixtee_cli.py`): Starts the interactive AI assistant shell.
* `nixtee configure`: Launches the terminal configuration wizard to save your Nixtee API Key and Secret.
* `nixtee mcp [OPTIONS]`: Starts a Model Context Protocol (MCP) server.
  - `--transport <stdio|sse>` (default: `stdio`)
  - `--port <integer>` (default: `8000`, only for `sse` transport)

---

### Interactive Chat Session Slash Commands

When running the interactive chat session (via `nixtee`), you can enter standard chat prompts or use these helper commands:

| Command | Action |
| :--- | :--- |
| `/help` | Displays help panel with all available slash commands. |
| `/usage` | Queries the Nixtee API for token usage stats (this month and last 5 hours). |
| `/history` | Fetches and displays a tabular log of past model predictions from the API. |
| `/configure` | Runs the API configuration wizard within the interactive session. |
| `/mcp` / `/mcp start` | Starts a background local SSE MCP server on port 8000. |
| `/mcp connect <cmd> [args...]` | Configures and registers external MCP servers in `~/.nixtee/credentials`. |
| `clear` | Clears the session memory and resets chat history (keeps system prompt). |
| `exit` / `quit` | Ends the interactive session. |

---

## QA & Manual Testing Protocols

Use these test cases to verify the correctness of the CLI system.

### Test Case 1: Configuration & Credentials Storage
1. Execute configuration:
   ```bash
   nixtee configure
   ```
2. Enter a mock API Key and Secret when prompted.
3. Verify that the file `~/.nixtee/credentials` has been created.
4. Verify the file contents using:
   ```bash
   cat ~/.nixtee/credentials
   ```
5. Ensure the directory and file permissions are secure:
   - Credentials directory permissions should be `0700` (`drwx------`).
   - Credentials file permissions should be `0600` (`-rw-------`).

### Test Case 2: Workspace Dataset Autodetection
1. Create a dummy dataset in the current directory:
   ```bash
   echo "feature1,feature2,feature3,label" > dummy_data.csv
   echo "0.1,0.2,0.3,1.0" >> dummy_data.csv
   echo "0.4,0.5,0.6,0.0" >> dummy_data.csv
   ```
2. Launch the interactive assistant:
   ```bash
   nixtee
   ```
3. Check the "Workspace Context" panel in the output. It should auto-detect and display:
   ```text
   Workspace Context: Found datasets: dummy_data.csv
   ```
4. Verify that Nixtee correctly parses the target column. It prioritizes columns named `target`, `y`, `label`, or `class`, or prompts you with a selectable menu if none are found.

### Test Case 3: Interactive Design and Optimization Loop
1. Start `nixtee` in interactive mode.
2. Ask the assistant to design a model:
   ```text
   You > Design a PyTorch network with 3 linear layers
   ```
3. The AI assistant should generate Python code defining a `Net` class inheriting from `torch.nn.Module`.
4. The CLI will detect this code block and prompt:
   ```text
   Detected Python code. Start automated optimization (up to 20 attempts)? [Y/n]
   ```
5. Confirm (`Y`). The CLI will perform an optimization loop:
   - Generates intermediate versions in `nixtee_models/optimized_model_v{attempt}.py`.
   - Sends the model graph and feature shapes (derived from your local CSV or default=10) to the API.
   - If estimated accuracy is below 80%, it auto-appends feedback and loops again (up to 20 times).
   - If accuracy plateaus (equal results 3 times in a row) or hits early success (>= 80%), it breaks early.
6. Check that the final `generated_model.py` is written in your root directory and contains injected hyperparameters (`NIXTEE_LEARNING_RATE`, etc.) and a custom training launcher.
7. Confirm the prompt to start training:
   ```text
   Would you like to start the training process with these optimized parameters? [y/N]
   ```
   Selecting `y` executes `python generated_model.py` to verify PyTorch integration.

### Test Case 4: Security & Static AST Sanitization
1. Create a malicious model definition file containing forbidden commands:
   ```bash
   echo "import os\nclass Net:\n  def __init__(self):\n    os.system('echo dangerous')\n" > malicious_model.py
   ```
2. Test loading the model. If you trigger prediction on this model, the AST analyzer (`is_code_safe`) will catch this execution.
3. Try starting the CLI and pasting code containing `import os; os.system(...)`.
4. Ensure the program halts the execution of the model and displays the security alert panel:
   ```text
   ⚠️ Security Alert: Potential malicious code detected!
   The AI generated code containing forbidden calls: ['forbidden call: os.system']
   Execution has been blocked for your safety.
   ```

### Test Case 5: Model Context Protocol (MCP) Server
1. Launch the MCP server via the CLI:
   ```bash
   nixtee mcp --transport sse --port 8000
   ```
2. Verify that it launches without error and reports:
   ```text
   Starting Nixtee MCP Server (sse)...
   ```
3. Connect using an MCP client (such as Claude Desktop or via the `npx @modelcontextprotocol/inspector` client).
4. Verify that two tools are registered and functional:
   - `list_datasets`: Scans the workspace and lists CSV files.
   - `predict_performance`: Takes python model code and returns performance prediction results.

---

## Development & Code Structure

The repository core logic is housed in a single Python script for simplicity:
- [nixtee_cli.py](file:///Users/alesjandera/Public/work/nixtee-cli/nixtee_cli.py) - Contains:
  - CLI definition using Click.
  - AST-based code validation logic (`is_code_safe`).
  - Dynamic module loader (`load_model_from_file`).
  - PyTorch trace to GNN-compatible schema translation (`extract_nixtee_graph`).
  - Ollama process synchronization & API communication layers.
  - Interactive chat session handling with tab completion and Rich terminal graphics.

### Adding CLI Commands

Add a new subcommand to the Click group inside [nixtee_cli.py](file:///Users/alesjandera/Public/work/nixtee-cli/nixtee_cli.py):

```python
@cli.command()
@click.option('--flag', default=True, help="Description of flag")
def my_command(flag):
    """Help documentation for my new command."""
    click.echo(f"Executed command with flag={flag}")
```

### Customizing the AST Security Engine

You can restrict more functions or modify safety rules in [nixtee_cli.py](file:///Users/alesjandera/Public/work/nixtee-cli/nixtee_cli.py). Update the `FORBIDDEN_CALLS` set:

```python
FORBIDDEN_CALLS = {
    'os.system', 'subprocess', 'eval', 'exec', 'open', 
    '__import__', 'compile', 'input', 'shutil.rmtree',
    # Add new blocked operations here:
    'urllib.request', 'socket'
}
```

### Registering Custom MCP Tools

To add tools to the MCP server, register them with the `mcp_server` instance under the `mcp` CLI command function:

```python
@mcp_server.tool()
def get_workspace_info() -> str:
    """Returns directory path info for debugging."""
    return str(os.getcwd())
```
