nixtee-cli 0.9.6

GNN-based Neural Network Performance and hyperparameters Predictor

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
2. Architecture & Storage Locations
3. Prerequisites
4. Installation & Setup
   • For Testers and Users (Quick Start)
   • For Developers (Local Development)
   • Using Nix (Reproducible Dev Shell)
5. Usage & CLI Commands
   • Interactive Chat Session Slash Commands
6. QA & Manual Testing Protocols
   • Test Case 1: Configuration & Credentials Storage
   • Test Case 2: Workspace Dataset Autodetection
   • Test Case 3: Interactive Design and Optimization Loop
   • Test Case 4: Security & Static AST Sanitization
   • Test Case 5: Model Context Protocol (MCP) Server
7. Development & Code Structure
   • Adding CLI Commands
   • Customizing the AST Security Engine
   • 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:

pip install .

Alternatively, if you use Nix, run the CLI instantly without installing dependencies:

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:

   git clone https://github.com/ajandera/nixtee-cli.git
   cd nixtee-cli
   

2. Set up a Python Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install in Editable Mode with Dependencies:

   pip install -e .
   

4. Verify Development Mode Setup: Run nixtee --help or run the script directly:

   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:

nix develop

Inside this shell, run the script directly via:

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:

   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:

   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:

   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:

   nixtee
   

3. Check the "Workspace Context" panel in the output. It should auto-detect and display:

   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:

   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:

   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:

   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:

   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:

   ⚠️ 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:

   nixtee mcp --transport sse --port 8000
   

2. Verify that it launches without error and reports:

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

@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. Update the FORBIDDEN_CALLS set:

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:

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