nlp2cmd

Schema System Architecture

Overview

System schematów w NLP2CMD pozwala na ekstrakcję, przechowywanie i wykorzystanie metadanych poleceń do generowania precyzyjnych komend z naturalnego języka.

Core Concepts

Schema

Schema opisuje strukturę polecenia:

{
  "command": "docker",
  "version": "1.0",
  "description": "Docker container management",
  "category": "container",
  "parameters": [
    {
      "name": "image",
      "type": "string",
      "required": true,
      "description": "Container image"
    }
  ],
  "templates": [
    "docker run {image}",
    "docker run -d {image}"
  ]
}

Components

1. Schema Extraction (src/nlp2cmd/schema_extraction/)

Ekstrakcja schematów z różnych źródeł:

Key Classes:

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")

2. Schema Storage (src/nlp2cmd/storage/)

Przechowywanie schematów w command_schemas/:

Structure:

command_schemas/
├── commands/           # Individual command schemas (per-command storage)
├── categories/         # Schema categories index
├── index.json          # Master index of all schemas
└── *.json              # Schema files (docker.json, nginx.json, etc.)

3. Schema-Based Generation (src/nlp2cmd/generation/schema/)

Note: Module przeniesiony z schema_based/ do generation/schema/ jako shims.

Generowanie komend na podstawie schematów:

# Historical API (deprecated shim)
from nlp2cmd.generation.schema import SchemaBasedGenerator

generator = SchemaBasedGenerator(llm_config)
command = generator.generate_command('find', {'path': '/home', 'pattern': '*.py'})

Usage Flow

1. User Input (NL)
      ↓
2. Schema Registry Lookup
      ↓
3. Schema-Based Generation
      ↓
4. Command Output

Versioning

Note: Wersjonowanie schematów jest obecnie ograniczone do wersji “1.0”.

Planowane wsparcie dla wersjonowania:

{
  "command": "docker",
  "version": "1.0",
  "migration_notes": "v1→v2: --rm moved to run options (planned)"
}

Integration with Pipeline

Current State: Schematy są częściowo zintegrowane z pipeline NLP2CMD:

  1. Schema Extraction - SchemaRegistry ekstrahuje schematy z różnych źródeł
  2. Schema Storage - PerCommandSchemaStore przechowuje schematy
  3. Limited Integration - SchemaBasedGenerator używany w nielicznych miejscach

Planned Integration:

  1. Schema Match - sprawdź czy istnieje schema
  2. Template Match - użyj zapisanych szablonów
  3. LLM Fallback - generuj przez LLM jeśli brak schema

Best Practices

  1. Start with good schemas - Provide quality initial schemas
  2. Use per-command storage - Lepsza organizacja
  3. Collect feedback - Enable user feedback for improvement
  4. Validate generations - Check generated commands
  5. Version schemas - Track schema evolution

Configuration

# Schema extraction config
llm_config = {
    "model": "ollama/qwen2.5-coder:7b",
    "api_base": "http://localhost:11434",
    "temperature": 0.1,
    "max_tokens": 512,
}

# Registry config
registry_config = {
    "use_per_command_storage": True,
    "storage_dir": "./command_schemas",
    "use_llm": False  # Optional LLM extraction
}

Migration History

This site is open source. Improve this page.