nlp2cmd

NLP2CMD API Reference

Documentation Hub - Entry point for all docs
User Guide - Complete usage tutorial
CLI Reference - Command line usage
Python API Guide - Programmatic usage
Examples Guide - Practical examples
Schema System - Schema extraction
Thermodynamic Integration - Advanced optimization
Contributing Guide - Development guidelines
Installation Guide - Setup instructions (in main README)

Core Module

NLP2CMD

Main class for transforming natural language into DSL commands.

from nlp2cmd import NLP2CMD, SQLAdapter

nlp = NLP2CMD(
    adapter=SQLAdapter(dialect="postgresql"),
    validation_mode="strict"
)

result = nlp.transform("Show all users from Warsaw")

Constructor Parameters

Parameter	Type	Default	Description
`adapter`	`BaseDSLAdapter`	required	DSL adapter for command generation
`nlp_backend`	`NLPBackend`	`RuleBasedBackend()`	NLP processing backend
`validator`	`BaseValidator`	`None`	Command validator
`feedback_analyzer`	`FeedbackAnalyzer`	`None`	Feedback loop analyzer
`validation_mode`	`str`	`"normal"`	Validation strictness
`auto_fix`	`bool`	`False`	Auto-fix detected issues

Methods

`transform(text, context=None, dry_run=False) -> TransformResult`

Transform natural language text into a DSL command.

Parameters:

text (str): Natural language input
context (dict, optional): Additional context
dry_run (bool): If True, don’t execute, just generate

Returns: TransformResult

Example:

result = nlp.transform(
    "Find users registered last month",
    context={"table_prefix": "app_"}
)
print(result.command)
print(result.confidence)

`set_context(key, value)`

Set a context value for subsequent transformations.

`clear_context()`

Clear all context.

`get_history() -> list[TransformResult]`

Get transformation history.

TransformResult

Result of a transformation operation.

Attributes

Attribute	Type	Description
`status`	`TransformStatus`	Status of transformation
`command`	`str`	Generated command
`plan`	`ExecutionPlan`	Execution plan
`confidence`	`float`	Confidence score (0.0-1.0)
`dsl_type`	`str`	DSL type name
`errors`	`list[str]`	Error messages
`warnings`	`list[str]`	Warning messages
`metadata`	`dict`	Additional metadata
`entities`	`dict`	Extracted entities
`intent`	`str`	Detected intent

Properties

is_success (bool): Check if transformation was successful
is_blocked (bool): Check if blocked by security policy

Adapters

SQLAdapter

SQL adapter supporting PostgreSQL, MySQL, SQLite, and MSSQL.

from nlp2cmd import SQLAdapter, SQLSafetyPolicy

adapter = SQLAdapter(
    dialect="postgresql",
    schema_context={
        "tables": ["users", "orders", "products"],
        "relations": {
            "orders.user_id": "users.id"
        }
    },
    safety_policy=SQLSafetyPolicy(
        allow_delete=False,
        require_where_on_update=True
    )
)

Supported Dialects

postgresql
mysql
sqlite
mssql

SQLSafetyPolicy

Option	Type	Default	Description
`allow_delete`	bool	False	Allow DELETE statements
`allow_truncate`	bool	False	Allow TRUNCATE
`allow_drop`	bool	False	Allow DROP
`require_where_on_update`	bool	True	Require WHERE on UPDATE
`require_where_on_delete`	bool	True	Require WHERE on DELETE
`max_rows_affected`	int	1000	Max rows limit
`blocked_tables`	list[str]	[]	Tables to block

ShellAdapter

Shell adapter for Bash, Zsh, Fish, and PowerShell.

from nlp2cmd import ShellAdapter, ShellSafetyPolicy

adapter = ShellAdapter(
    shell_type="bash",
    environment_context={
        "os": "linux",
        "available_tools": ["docker", "kubectl", "git"]
    },
    safety_policy=ShellSafetyPolicy(
        allow_sudo=False,
        blocked_commands=["rm -rf /"]
    )
)

ShellSafetyPolicy

Option	Type	Default	Description
`blocked_commands`	list[str]	[…]	Commands to block
`require_confirmation_for`	list[str]	[…]	Commands needing confirmation
`allow_sudo`	bool	False	Allow sudo
`allow_pipe_to_shell`	bool	False	Allow piping to sh/bash
`max_pipe_depth`	int	5	Max pipe chain depth
`sandbox_mode`	bool	True	Enable sandbox

DockerAdapter

Docker adapter for CLI and Compose operations.

from nlp2cmd import DockerAdapter, DockerSafetyPolicy

adapter = DockerAdapter(
    safety_policy=DockerSafetyPolicy(
        allow_privileged=False,
        require_image_tag=True
    )
)

DockerSafetyPolicy

Option	Type	Default	Description
`allow_privileged`	bool	False	Allow –privileged
`allow_host_network`	bool	False	Allow –network host
`allow_host_pid`	bool	False	Allow –pid host
`blocked_images`	list[str]	[]	Blocked images
`require_image_tag`	bool	True	Require image tags

KubernetesAdapter

Kubernetes adapter for kubectl commands.

from nlp2cmd import KubernetesAdapter, KubernetesSafetyPolicy

adapter = KubernetesAdapter(
    safety_policy=KubernetesSafetyPolicy(
        blocked_namespaces=["kube-system"],
        allow_delete=False
    )
)

KubernetesSafetyPolicy

Option	Type	Default	Description
`allowed_namespaces`	list[str]	[“default”]	Allowed namespaces
`blocked_namespaces`	list[str]	[…]	Blocked namespaces
`allow_delete`	bool	False	Allow delete operations
`allow_exec`	bool	True	Allow exec into pods
`max_replicas`	int	10	Max replica count

DQLAdapter

Doctrine Query Language adapter for PHP/Symfony.

from nlp2cmd import DQLAdapter

adapter = DQLAdapter(
    entity_context={
        "entities": {
            "User": {"fields": ["id", "name", "email"]},
            "Order": {"fields": ["id", "user_id", "total"]}
        }
    }
)

BrowserAdapter

Browser automation adapter using Playwright.

from nlp2cmd import BrowserAdapter

adapter = BrowserAdapter(
    headless=True,
    browser="chromium",
    timeout=30000
)

Supported Browsers

chromium
firefox
webkit

DesktopAdapter

Desktop GUI automation adapter.

from nlp2cmd import DesktopAdapter

adapter = DesktopAdapter(
    platform="linux",
    backend="xdotool"
)

CanvasAdapter

Canvas drawing adapter for web-based drawing tools.

from nlp2cmd import CanvasAdapter

adapter = CanvasAdapter(
    default_site="jspaint",
    color_support=True
)

Schemas

SchemaRegistry

Registry for file format validation and repair.

from nlp2cmd import SchemaRegistry

registry = SchemaRegistry()

# Detect format
schema = registry.detect_format(Path("docker-compose.yml"))

# Validate
result = registry.validate(content, "docker-compose")

# Repair
repaired = registry.repair(content, "docker-compose", auto_fix=True)

Supported Formats

Dockerfile
docker-compose.yml
Kubernetes manifests
GitHub Actions workflows
.env files
nginx.conf
SQL migrations

Feedback

FeedbackAnalyzer

Analyzes transformation results and provides feedback.

from nlp2cmd import FeedbackAnalyzer

analyzer = FeedbackAnalyzer()

feedback = analyzer.analyze(
    original_input="Delete all users",
    generated_output="DELETE FROM users;",
    validation_errors=["Missing WHERE clause"],
    dsl_type="sql"
)

print(feedback.suggestions)

FeedbackResult

Attribute	Type	Description
`type`	`FeedbackType`	Feedback type
`original_input`	`str`	Original input
`generated_output`	`str`	Generated command
`errors`	`list[str]`	Errors
`warnings`	`list[str]`	Warnings
`suggestions`	`list[str]`	Suggestions
`auto_corrections`	`dict`	Auto-corrections
`confidence`	`float`	Confidence score

Environment

EnvironmentAnalyzer

Analyzes the system environment.

from nlp2cmd import EnvironmentAnalyzer

analyzer = EnvironmentAnalyzer()

# Basic analysis
env = analyzer.analyze()

# Detect tools
tools = analyzer.detect_tools(["docker", "kubectl", "git"])

# Check services
services = analyzer.check_services()

# Find config files
configs = analyzer.find_config_files(Path.cwd())

# Full report
report = analyzer.full_report()

Thermodynamic Optimization API

HybridThermodynamicGenerator

Routes between DSL generation and thermodynamic optimization based on problem complexity.

from nlp2cmd.generation import create_hybrid_generator

# Create hybrid generator
hybrid = create_hybrid_generator()

# Generate solution
result = await hybrid.generate("Zaplanuj 5 zadań w 10 slotach")
print(result['source'])  # 'dsl' or 'thermodynamic'

ThermodynamicGenerator

Direct thermodynamic optimization using Langevin dynamics.

from nlp2cmd.generation import create_thermodynamic_generator

# Create generator
thermo = create_thermodynamic_generator(
    n_samples=5,      # Multiple solutions
    n_steps=500,      # Langevin steps
)

# Generate solution
result = await thermo.generate("Zaplanuj 5 zadań w 10 slotach")
print(result.decoded_output)
print(result.energy_estimate)

Energy Models

Domain-specific energy functions for constraint satisfaction.

from nlp2cmd.generation.thermodynamic import (
    SchedulingEnergy,
    AllocationEnergy,
    ConstraintEnergy,
)

# Scheduling energy model
energy = SchedulingEnergy()

# Add custom constraint
energy.add_penalty(
    "custom_constraint",
    lambda z, c: violation_function(z, c),
    lambda z, c: gradient_function(z, c),
    weight=10.0
)

Langevin Configuration

Configure Langevin dynamics sampling parameters.

from nlp2cmd.generation.thermodynamic import LangevinConfig

config = LangevinConfig(
    mu=1.0,              # Mobility coefficient
    kT=0.5,              # Thermal energy
    dt=0.01,             # Time step
    n_steps=1000,        # Integration steps
    dim=64,              # Latent dimension
    record_trajectory=True,
)

LLM as Planner Architecture

DecisionRouter

Routes requests to direct execution or LLM planner based on complexity.

from nlp2cmd import DecisionRouter, RouterConfig

router = DecisionRouter(RouterConfig(
    use_llm_for_complex=True,
    complexity_threshold=0.7
))

result = router.route("Create a complex dashboard with charts")

ActionRegistry

Registry of available actions with schema validation.

from nlp2cmd import get_registry, ActionSchema

registry = get_registry()

# Register new action
registry.register("custom_action", ActionSchema(
    name="custom_action",
    description="Custom action description",
    parameters=[...]
))

# List actions
actions = registry.list_actions()

LLMPlanner

Generates multi-step execution plans using LLM.

from nlp2cmd import LLMPlanner, PlannerConfig

planner = LLMPlanner(PlannerConfig(
    model="gpt-4",
    max_steps=10
))

plan = await planner.plan("Deploy application to production")

PlanExecutor

Executes validated plans with error handling.

from nlp2cmd import PlanExecutor

executor = PlanExecutor()

# Execute plan
result = await executor.execute(plan)

# Execute with context
result = await executor.execute(plan, context={
    "workspace": "/path/to/project"
})

ResultAggregator

Aggregates and formats execution results.

from nlp2cmd import ResultAggregator, OutputFormat

aggregator = ResultAggregator()

# Aggregate results
aggregated = aggregator.aggregate(results)

# Format output
formatted = aggregator.format(aggregated, OutputFormat.MARKDOWN)

Evolutionary Orchestrator

EvolutionaryRecoveryEngine

Advanced error recovery with evolutionary strategies.

from nlp2cmd import EvolutionaryRecoveryEngine, RecoveryStrategy

recovery = EvolutionaryRecoveryEngine()

# Recover from failure
result = await recovery.recover(
    failed_command="docker run invalid_image",
    error="image not found",
    strategy=RecoveryStrategy.ADAPTIVE
)

AutonomousExampleRunner

Runs autonomous examples with self-healing.

from nlp2cmd import AutonomousExampleRunner

runner = AutonomousExampleRunner()

# Run example with recovery
result = await runner.run_example(
    example_path="examples/complex_automation.py",
    enable_recovery=True
)

Additional Components

Schema Extraction

from nlp2cmd.schema_extraction import SchemaRegistry

registry = SchemaRegistry(
    use_per_command_storage=True,
    storage_dir="./command_schemas"
)

# Extract from command help
schema = registry.register_shell_help("docker")

# Extract from OpenAPI
schema = registry.register_openapi_schema("https://api.example.com/openapi.json")

LLM Router

from nlp2cmd.llm import get_router, classify_task

router = get_router()

# Route task to appropriate model
response = await router.route(
    task="coding",
    prompt="Write a Python function"
)

# Classify task type
task_type = classify_task("Draw a red circle")

CLI Reference

# Interactive mode
nlp2cmd --interactive

# Single query
nlp2cmd --query "Find large files"

# Repair file
nlp2cmd --repair docker-compose.yml --backup

# Validate file
nlp2cmd --validate ./k8s/*.yaml

# Analyze environment
nlp2cmd --analyze-env --output report.json

# Watch mode
nlp2cmd --watch ./config/ --format kubernetes

CLI Options

Option	Description
`-i, --interactive`	Interactive REPL mode
`-d, --dsl`	DSL type (auto, sql, shell, docker, kubernetes)
`-f, --files`	Files to process
`-s, --schema`	Schema file (JSON/YAML)
`-w, --watch`	Watch directory for changes
`--repair`	Repair configuration file
`--validate`	Validate file
`--analyze-env`	Analyze environment
`-o, --output`	Output file
`--auto-repair`	Auto-fix issues
`--backup`	Create backups
`-q, --query`	Single query

This site is open source. Improve this page.