VTK Prompt

A command-line interface and web-based UI for generating VTK visualization code using Large Language Models (Anthropic Claude, OpenAI GPT, NVIDIA NIM, and local models).

Features

Multiple LLM providers: Anthropic Claude, OpenAI GPT, NVIDIA NIM, and local models
Interactive web UI with live VTK rendering
Context-enhanced generation via vtk-mcp: semantic search over VTK examples and docs, class API lookup, and full code validation
Real-time visualization of generated code
Token usage tracking and cost monitoring
CLI and Python API for integration

Installation

From PyPI (Stable)

# pip
pip install vtk-prompt

# uv (recommended)
uv pip install vtk-prompt

From TestPyPI (Latest Development)

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ vtk-prompt

From Source

git clone https://github.com/vicentebolea/vtk-prompt.git
cd vtk-prompt

# pip
pip install -e .

# uv
uv pip install -e .

Quick Start

1. Set up API keys

export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENAI_API_KEY="your-openai-key"  # Optional

2. Launch Web UI (Recommended)

vtk-prompt-ui

Access the UI at http://localhost:8080

3. Or use CLI

# Generate VTK code
vtk-prompt "Create a red sphere" -t $ANTHROPIC_API_KEY

# With vtk-mcp for context-enhanced generation
vtk-prompt "Create a sphere with custom resolution" --mcp-url http://localhost:8000 -t $API_KEY

# Different providers
vtk-prompt "Create a blue cube" --provider openai -t $OPENAI_API_KEY
vtk-prompt "Create a cone" --provider nim --token YOUR_NIM_TOKEN

Usage

Web UI Features

The web interface provides:

Model selection: Choose between Claude models (Haiku, Sonnet 4) and other providers
Token control: Adjust maximum tokens for responses
Usage tracking: Real-time display of input/output tokens and costs
vtk-mcp integration: Enter a vtk-mcp server URL to enable context retrieval and code validation
Live preview: See VTK visualizations rendered in real-time
Code export: View, edit, and copy generated VTK code
Local & cloud support: Both cloud APIs and local model endpoints

Command Line Interface

# Basic usage
vtk-prompt "Create a red sphere" -t $API_KEY

# Advanced options
vtk-prompt "Create a textured cone with 32 resolution" \
  --provider anthropic \
  --model claude-opus-4-7 \
  --max-tokens 4000 \
  --mcp-url http://localhost:8000 \
  --verbose \
  -t $API_KEY

# Using different providers
vtk-prompt "Create a blue cube" --provider openai --model gpt-4.1 -t $OPENAI_API_KEY
vtk-prompt "Create a cylinder" --provider nim --model meta/llama-3.3-70b-instruct -t $NIM_KEY

vtk-mcp Integration

Context-enhanced generation is powered by vtk-mcp, a local MCP server that exposes VTK knowledge tools to the LLM.

Start vtk-mcp (see its README for setup):

docker compose up   # or: uvicorn vtk_mcp.transport.http:app --port 8000

Use with vtk-prompt:

vtk-prompt "Create a vtkSphereSource with texture mapping" --mcp-url http://localhost:8000 -t $API_KEY

When --mcp-url is set the LLM has access to all vtk-mcp tools during generation (class lookup, method signatures, import validation, semantic search) and the generated code is validated against the VTK API with validate_vtk_code before being returned.

Python API

from vtk_prompt import VTKPromptClient

client = VTKPromptClient()
code = client.generate_code("Create a red sphere")
print(code)

Model Configuration

Model configuration with YAML prompt files:

# Model and parameter configuration
model: anthropic/claude-opus-4-1-20250805
modelParameters:
  temperature: 0.2
  max_tokens: 6000

Using custom prompt files:

# CLI: Use your custom prompt file
vtk-prompt "Create a sphere" --prompt-file custom_vtk_prompt.yml

# CLI: Or with additional CLI overrides
vtk-prompt "Create a complex scene" --prompt-file custom_vtk_prompt.yml --retry-attempts 3

# UI: Use your custom prompt file
vtk-prompt-ui --server --prompt-file custom_vtk_prompt.yml

Model Parameters Guide

Temperature Settings:

0.1-0.3: More focused, deterministic code generation
0.4-0.7: Balanced creativity and consistency (recommended)
0.8-1.0: More creative but potentially less reliable

Token Limits: Token usage can vary significantly between models and providers. These are general guidelines:

1000-2000: Simple visualizations and basic VTK objects
3000-4000: Complex scenes with multiple objects
5000+: Detailed implementations with extensive documentation

Note: Different models have different token limits and costs. Check your provider's documentation for specific model capabilities.

Testing

# Run all tests with tox
tox -e test

# Or directly with pytest (pip or uv)
pip install -e ".[test]" && pytest
uv pip install -e ".[test]" && pytest

Configuration

Environment Variables

ANTHROPIC_API_KEY - Anthropic Claude API key
OPENAI_API_KEY - OpenAI API key (also used for NVIDIA NIM)

Supported Providers & Models

Provider	Default Model	Base URL
anthropic	claude-sonnet-4-6	https://api.anthropic.com/v1
openai	gpt-4.1	https://api.openai.com/v1
gemini	gemini-2.5-pro	https://generativelanguage.googleapis.com/v1beta
nim	meta/llama-3.3-70b-instruct	https://integrate.api.nvidia.com/v1
custom	User-defined	User-defined (for local models)

Custom/Local Models

You can use local models via OpenAI-compatible APIs:

# Using Ollama
vtk-prompt "Create a sphere" \
  --provider custom \
  --base-url http://localhost:11434/v1 \
  --model llama2

# Using LM Studio
vtk-prompt "Create a cube" \
  --provider custom \
  --base-url http://localhost:1234/v1 \
  --model local-model

CLI Reference

Usage: vtk-prompt [OPTIONS] INPUT_STRING

  Generate and execute VTK code using LLMs.

Options:
  --provider [openai|anthropic|gemini|nim]
                                  LLM provider to use
  -m, --model TEXT                Model name to use
  -k, --max-tokens INTEGER        Max # of tokens to generate
  --temperature FLOAT             Temperature for generation (0.0-2.0)
  -t, --token TEXT                API token for the selected provider [required]
  --base-url TEXT                 Base URL for API (auto-detected or custom)
  -v, --verbose                   Show generated source code
  --mcp-url TEXT                  vtk-mcp server URL (enables context retrieval and code validation)
  --top-k INTEGER                 Number of examples to retrieve from vtk-mcp
  --retry-attempts INTEGER        Number of times to retry if validation fails
  --conversation TEXT             Path to conversation file for chat history
  --prompt-file TEXT              Path to custom YAML prompt file
  --help                          Show this message and exit.

Available Commands

vtk-prompt - Main CLI for code generation
vtk-prompt-ui - Launch web interface
gen-vtk-file - Generate VTK XML files

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For detailed development instructions, see DEVELOPMENT.md which covers:

Setting up the development environment
Running tests and linting
Developer mode for the web UI
Code formatting and type checking
Pre-commit hooks

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Testing

The project includes a comprehensive test suite with code coverage reporting.

Running Tests

# Run all tests with coverage
pytest

# Run specific test categories
pytest tests/test_cli.py                    # CLI functionality tests
pytest tests/test_providers_smoke.py        # Provider smoke tests
pytest -m "not smoke"                       # Exclude API-dependent tests

# Generate coverage report
pytest --cov=src/vtk_prompt --cov-report=html

Test Categories

CLI Tests: Argument parsing, provider integration, error handling
Smoke Tests: Real API connectivity testing (requires API keys)
Client Tests: Core VTKPromptClient functionality
Integration Tests: End-to-end workflow testing

Coverage reports are generated in htmlcov/ directory. Current coverage: 11.0% (improving with ongoing test development).

License

This project is licensed under the MIT License - see the LICENSE file for details.

Architecture

Core: Python package with CLI and API
UI: Trame-based web interface with VTK rendering
vtk-mcp: External MCP server providing VTK knowledge, semantic search, and code validation
Providers: Unified interface for multiple LLM APIs

Links

Made with care for the VTK and scientific visualization community.

Name		Name	Last commit message	Last commit date
Latest commit History 158 Commits
.github/workflows		.github/workflows
src/vtk_prompt		src/vtk_prompt
tests		tests
.gitignore		.gitignore
.gitmodules		.gitmodules
.pre-commit-config.yaml		.pre-commit-config.yaml
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

VTK Prompt

Features

Installation

From PyPI (Stable)

From TestPyPI (Latest Development)

From Source

Quick Start

1. Set up API keys

2. Launch Web UI (Recommended)

3. Or use CLI

Usage

Web UI Features

Command Line Interface

vtk-mcp Integration

Python API

Model Configuration

Model Parameters Guide

Testing

Configuration

Environment Variables

Supported Providers & Models

Custom/Local Models

CLI Reference

Available Commands

Contributing

Testing

Running Tests

Test Categories

License

Architecture

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages