its-compiler-cli


Nameits-compiler-cli JSON
Version 1.0.4 PyPI version JSON
download
home_pageNone
SummaryCommand-line interface for ITS Compiler - converts ITS templates to AI prompts
upload_time2025-07-21 17:36:44
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseNone
keywords its instruction template specification ai prompt cli command-line compilation
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # ITS Compiler CLI

[![PyPI version](https://img.shields.io/pypi/v/its-compiler-cli.svg)](https://pypi.org/project/its-compiler-cli/)
[![Python](https://img.shields.io/pypi/pyversions/its-compiler-cli.svg)](https://pypi.org/project/its-compiler-cli/)
[![License](https://img.shields.io/github/license/AlexanderParker/its-compiler-cli-python.svg)](LICENSE)

Command-line interface for the [ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python) library. Converts [Instruction Template Specification (ITS)](https://alexanderparker.github.io/instruction-template-specification/) templates into structured AI prompts.

## Installation

```bash
pip install its-compiler-cli
```

This automatically installs the core [its-compiler](https://github.com/alexanderparker/its-compiler-python) library as a dependency.

## Quick Start

### Basic Usage

```bash
# Compile template to stdout
its-compile template.json

# Save output to file
its-compile template.json --output prompt.txt

# Use custom variables
its-compile template.json --variables vars.json

# Validate template without compiling
its-compile template.json --validate-only
```

### Example Template

Create `example.json`:

```json
{
  "version": "1.0.0",
  "extends": ["https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-standard-types-v1.json"],
  "variables": {
    "topic": "renewable energy"
  },
  "content": [
    {
      "type": "placeholder",
      "instructionType": "paragraph",
      "config": {
        "description": "Write about ${topic}",
        "tone": "informative"
      }
    }
  ]
}
```

Compile it:

```bash
its-compile example.json
```

## Command Reference

```
its-compile [OPTIONS] TEMPLATE_FILE

Arguments:
  TEMPLATE_FILE             Path to the ITS template JSON file

Options:
  -o, --output FILE         Output file (default: stdout)
  -v, --variables FILE      JSON file with variable values
  -w, --watch              Watch template file for changes
  --validate-only          Validate template without compiling
  --verbose                Show detailed output
  --strict                 Enable strict validation mode
  --no-cache              Disable schema caching
  --timeout INTEGER       Network timeout in seconds (default: 30)
  --allow-http            Allow HTTP URLs (not recommended)
  --interactive-allowlist / --no-interactive-allowlist
                          Enable/disable interactive schema prompts
  --allowlist-status      Show schema allowlist status
  --version               Show version and exit
  --help                  Show help and exit
```

## Development Workflow

### Watch Mode

Automatically recompile when the template changes:

```bash
its-compile template.json --watch --output prompt.txt
```

### Validation

Check templates for errors without compiling:

```bash
its-compile template.json --validate-only --strict
```

### Variables

Use external variable files:

```bash
# vars.json
{
  "productName": "Widget Pro",
  "features": ["fast", "reliable", "secure"]
}

its-compile template.json --variables vars.json
```

## Schema Management

When templates reference external schemas, you may be prompted to allow them:

```
SCHEMA ALLOWLIST DECISION REQUIRED
URL: https://example.com/schema.json

1. Allow permanently (saved to allowlist)
2. Allow for this session only
3. Deny (compilation will fail)
```

### Allowlist Commands

```bash
# Check current allowlist status
its-compile --allowlist-status

# Non-interactive mode (useful for CI/CD)
its-compile template.json --no-interactive-allowlist
```

## Configuration

Set environment variables to configure default behaviour:

```bash
export ITS_INTERACTIVE_ALLOWLIST=false  # Disable prompts
export ITS_REQUEST_TIMEOUT=60           # Increase timeout
export ITS_ALLOWLIST_FILE=/path/to/allowlist.json
```

## Error Examples

### Missing Variable

```
✗ Variable Error: Undefined variable '${productName}'
  Available variables: topic, features
```

### Invalid Template

```
✗ Validation Error: Missing required field 'version'
  At: root
```

### Schema Issues

```
✗ Schema Error: Failed to load schema
  URL: https://example.com/schema.json
```

## Testing

Test your CLI installation:

```bash
# Basic functionality test
echo '{"version":"1.0.0","content":[{"type":"text","text":"Hello"}]}' | its-compile /dev/stdin

# Download test runner (optional)
curl -O https://raw.githubusercontent.com/AlexanderParker/its-compiler-cli-python/main/test_runner.py
python test_runner.py
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes and add tests
4. Ensure all tests pass (`python test_runner.py`)
5. Run linting (`black . && flake8`)
6. Commit your changes
7. Push to the branch and open a Pull Request

### Development Setup

```bash
# Clone and setup
git clone https://github.com/AlexanderParker/its-compiler-cli-python.git
cd its-compiler-cli-python

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
python test_runner.py
```

### For Maintainers

**Publishing to PyPI:**

This package is published to PyPI as `its-compiler-cli`. Releases are currently managed manually:

```bash
# Build the package
python -m build

# Test upload to TestPyPI first (recommended)
python -m twine upload --repository testpypi dist/*

# Upload to production PyPI (requires appropriate credentials)
python -m twine upload dist/*
```

**TestPyPI Testing:**

```bash
# Install from TestPyPI to verify the package
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ its-compiler-cli
```

## Related Projects

- **[ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python)** - Core library
- **[Instruction Template Specification](https://alexanderparker.github.io/instruction-template-specification/)** - Official specification
- **[ITS Example Templates](https://github.com/AlexanderParker/its-example-templates)** - Example templates

## License

MIT License - see the [LICENSE](LICENSE) file for details.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "its-compiler-cli",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": "Alexander Parker <pypi@parker.im>",
    "keywords": "its, instruction, template, specification, ai, prompt, cli, command-line, compilation",
    "author": null,
    "author_email": "Alexander Parker <pypi@parker.im>",
    "download_url": "https://files.pythonhosted.org/packages/b7/c5/a3c2d60c0112baa42c0ed420d002b0984c7f03c42d1e3887ea1f3da81100/its_compiler_cli-1.0.4.tar.gz",
    "platform": null,
    "description": "# ITS Compiler CLI\r\n\r\n[![PyPI version](https://img.shields.io/pypi/v/its-compiler-cli.svg)](https://pypi.org/project/its-compiler-cli/)\r\n[![Python](https://img.shields.io/pypi/pyversions/its-compiler-cli.svg)](https://pypi.org/project/its-compiler-cli/)\r\n[![License](https://img.shields.io/github/license/AlexanderParker/its-compiler-cli-python.svg)](LICENSE)\r\n\r\nCommand-line interface for the [ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python) library. Converts [Instruction Template Specification (ITS)](https://alexanderparker.github.io/instruction-template-specification/) templates into structured AI prompts.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install its-compiler-cli\r\n```\r\n\r\nThis automatically installs the core [its-compiler](https://github.com/alexanderparker/its-compiler-python) library as a dependency.\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Compile template to stdout\r\nits-compile template.json\r\n\r\n# Save output to file\r\nits-compile template.json --output prompt.txt\r\n\r\n# Use custom variables\r\nits-compile template.json --variables vars.json\r\n\r\n# Validate template without compiling\r\nits-compile template.json --validate-only\r\n```\r\n\r\n### Example Template\r\n\r\nCreate `example.json`:\r\n\r\n```json\r\n{\r\n  \"version\": \"1.0.0\",\r\n  \"extends\": [\"https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-standard-types-v1.json\"],\r\n  \"variables\": {\r\n    \"topic\": \"renewable energy\"\r\n  },\r\n  \"content\": [\r\n    {\r\n      \"type\": \"placeholder\",\r\n      \"instructionType\": \"paragraph\",\r\n      \"config\": {\r\n        \"description\": \"Write about ${topic}\",\r\n        \"tone\": \"informative\"\r\n      }\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\nCompile it:\r\n\r\n```bash\r\nits-compile example.json\r\n```\r\n\r\n## Command Reference\r\n\r\n```\r\nits-compile [OPTIONS] TEMPLATE_FILE\r\n\r\nArguments:\r\n  TEMPLATE_FILE             Path to the ITS template JSON file\r\n\r\nOptions:\r\n  -o, --output FILE         Output file (default: stdout)\r\n  -v, --variables FILE      JSON file with variable values\r\n  -w, --watch              Watch template file for changes\r\n  --validate-only          Validate template without compiling\r\n  --verbose                Show detailed output\r\n  --strict                 Enable strict validation mode\r\n  --no-cache              Disable schema caching\r\n  --timeout INTEGER       Network timeout in seconds (default: 30)\r\n  --allow-http            Allow HTTP URLs (not recommended)\r\n  --interactive-allowlist / --no-interactive-allowlist\r\n                          Enable/disable interactive schema prompts\r\n  --allowlist-status      Show schema allowlist status\r\n  --version               Show version and exit\r\n  --help                  Show help and exit\r\n```\r\n\r\n## Development Workflow\r\n\r\n### Watch Mode\r\n\r\nAutomatically recompile when the template changes:\r\n\r\n```bash\r\nits-compile template.json --watch --output prompt.txt\r\n```\r\n\r\n### Validation\r\n\r\nCheck templates for errors without compiling:\r\n\r\n```bash\r\nits-compile template.json --validate-only --strict\r\n```\r\n\r\n### Variables\r\n\r\nUse external variable files:\r\n\r\n```bash\r\n# vars.json\r\n{\r\n  \"productName\": \"Widget Pro\",\r\n  \"features\": [\"fast\", \"reliable\", \"secure\"]\r\n}\r\n\r\nits-compile template.json --variables vars.json\r\n```\r\n\r\n## Schema Management\r\n\r\nWhen templates reference external schemas, you may be prompted to allow them:\r\n\r\n```\r\nSCHEMA ALLOWLIST DECISION REQUIRED\r\nURL: https://example.com/schema.json\r\n\r\n1. Allow permanently (saved to allowlist)\r\n2. Allow for this session only\r\n3. Deny (compilation will fail)\r\n```\r\n\r\n### Allowlist Commands\r\n\r\n```bash\r\n# Check current allowlist status\r\nits-compile --allowlist-status\r\n\r\n# Non-interactive mode (useful for CI/CD)\r\nits-compile template.json --no-interactive-allowlist\r\n```\r\n\r\n## Configuration\r\n\r\nSet environment variables to configure default behaviour:\r\n\r\n```bash\r\nexport ITS_INTERACTIVE_ALLOWLIST=false  # Disable prompts\r\nexport ITS_REQUEST_TIMEOUT=60           # Increase timeout\r\nexport ITS_ALLOWLIST_FILE=/path/to/allowlist.json\r\n```\r\n\r\n## Error Examples\r\n\r\n### Missing Variable\r\n\r\n```\r\n\u2717 Variable Error: Undefined variable '${productName}'\r\n  Available variables: topic, features\r\n```\r\n\r\n### Invalid Template\r\n\r\n```\r\n\u2717 Validation Error: Missing required field 'version'\r\n  At: root\r\n```\r\n\r\n### Schema Issues\r\n\r\n```\r\n\u2717 Schema Error: Failed to load schema\r\n  URL: https://example.com/schema.json\r\n```\r\n\r\n## Testing\r\n\r\nTest your CLI installation:\r\n\r\n```bash\r\n# Basic functionality test\r\necho '{\"version\":\"1.0.0\",\"content\":[{\"type\":\"text\",\"text\":\"Hello\"}]}' | its-compile /dev/stdin\r\n\r\n# Download test runner (optional)\r\ncurl -O https://raw.githubusercontent.com/AlexanderParker/its-compiler-cli-python/main/test_runner.py\r\npython test_runner.py\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Make your changes and add tests\r\n4. Ensure all tests pass (`python test_runner.py`)\r\n5. Run linting (`black . && flake8`)\r\n6. Commit your changes\r\n7. Push to the branch and open a Pull Request\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone and setup\r\ngit clone https://github.com/AlexanderParker/its-compiler-cli-python.git\r\ncd its-compiler-cli-python\r\n\r\n# Create and activate virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\r\n\r\n# Install in development mode\r\npip install -e \".[dev]\"\r\n\r\n# Run tests\r\npython test_runner.py\r\n```\r\n\r\n### For Maintainers\r\n\r\n**Publishing to PyPI:**\r\n\r\nThis package is published to PyPI as `its-compiler-cli`. Releases are currently managed manually:\r\n\r\n```bash\r\n# Build the package\r\npython -m build\r\n\r\n# Test upload to TestPyPI first (recommended)\r\npython -m twine upload --repository testpypi dist/*\r\n\r\n# Upload to production PyPI (requires appropriate credentials)\r\npython -m twine upload dist/*\r\n```\r\n\r\n**TestPyPI Testing:**\r\n\r\n```bash\r\n# Install from TestPyPI to verify the package\r\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ its-compiler-cli\r\n```\r\n\r\n## Related Projects\r\n\r\n- **[ITS Compiler Python](https://github.com/alexanderparker/its-compiler-python)** - Core library\r\n- **[Instruction Template Specification](https://alexanderparker.github.io/instruction-template-specification/)** - Official specification\r\n- **[ITS Example Templates](https://github.com/AlexanderParker/its-example-templates)** - Example templates\r\n\r\n## License\r\n\r\nMIT License - see the [LICENSE](LICENSE) file for details.\r\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Command-line interface for ITS Compiler - converts ITS templates to AI prompts",
    "version": "1.0.4",
    "project_urls": {
        "Bug Tracker": "https://github.com/alexanderparker/its-compiler-cli-python/issues",
        "Core Library": "https://github.com/alexanderparker/its-compiler-python",
        "Homepage": "https://github.com/alexanderparker/its-compiler-cli-python",
        "Repository": "https://github.com/alexanderparker/its-compiler-cli-python.git"
    },
    "split_keywords": [
        "its",
        " instruction",
        " template",
        " specification",
        " ai",
        " prompt",
        " cli",
        " command-line",
        " compilation"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4177daf0e2a5af5a440c90d7553410810af047a875c43d095b76d69364d606e5",
                "md5": "ac47788fb838f1eebeb8dd6cf8f8cb54",
                "sha256": "fbe62e5313fef96295916497f93cea5eb70a6d441a378fd2db512497e00045e5"
            },
            "downloads": -1,
            "filename": "its_compiler_cli-1.0.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ac47788fb838f1eebeb8dd6cf8f8cb54",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 13216,
            "upload_time": "2025-07-21T17:36:43",
            "upload_time_iso_8601": "2025-07-21T17:36:43.568516Z",
            "url": "https://files.pythonhosted.org/packages/41/77/daf0e2a5af5a440c90d7553410810af047a875c43d095b76d69364d606e5/its_compiler_cli-1.0.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b7c5a3c2d60c0112baa42c0ed420d002b0984c7f03c42d1e3887ea1f3da81100",
                "md5": "8ed5194a140e29a5927f4beb8f77b4b4",
                "sha256": "0bf45368a2793f282a576e51920ab51dd5f903257880bcb387083765c32f5fda"
            },
            "downloads": -1,
            "filename": "its_compiler_cli-1.0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "8ed5194a140e29a5927f4beb8f77b4b4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 16069,
            "upload_time": "2025-07-21T17:36:44",
            "upload_time_iso_8601": "2025-07-21T17:36:44.550905Z",
            "url": "https://files.pythonhosted.org/packages/b7/c5/a3c2d60c0112baa42c0ed420d002b0984c7f03c42d1e3887ea1f3da81100/its_compiler_cli-1.0.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-21 17:36:44",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "alexanderparker",
    "github_project": "its-compiler-cli-python",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "its-compiler-cli"
}
        
Elapsed time: 1.50610s