Metadata-Version: 2.4
Name: pictlang
Version: 0.2.1
Summary: Generate SVG images from a theme and style via an LLM-written Python DSL
Author: limloop
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/limloop/pictlang
Project-URL: Repository, https://github.com/limloop/pictlang
Project-URL: Issues, https://github.com/limloop/pictlang/issues
Keywords: svg,llm,openai,image-generation,dsl,ai,pictlang
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0
Requires-Dist: httpx>=0.25
Requires-Dist: platformdirs>=4.0
Provides-Extra: optimize
Requires-Dist: scour>=0.38; extra == "optimize"
Provides-Extra: socks
Requires-Dist: httpx[socks]>=0.25; extra == "socks"
Provides-Extra: all
Requires-Dist: scour>=0.38; extra == "all"
Requires-Dist: httpx[socks]>=0.25; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# pictlang

[![tests](https://github.com/limloop/pictlang/actions/workflows/tests.yml/badge.svg)](https://github.com/limloop/pictlang/actions/workflows/tests.yml)
[![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/limloop/pictlang/blob/main/LICENSE)
[![python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/limloop/pictlang/blob/main/pyproject.toml)
[![pypi](https://img.shields.io/pypi/v/pictlang.svg)](https://pypi.org/project/pictlang/)
[![pypi-downloads](https://img.shields.io/pypi/dm/pictlang.svg)](https://pypi.org/project/pictlang/)

Generate SVG images from a theme and style via an LLM-written Python DSL.

<p align="center">
  <img src="https://raw.githubusercontent.com/limloop/pictlang/main/examples/bauhaus-city/output.svg" width="180">
  <img src="https://raw.githubusercontent.com/limloop/pictlang/main/examples/hud-interface/output.svg" width="180">
  <img src="https://raw.githubusercontent.com/limloop/pictlang/main/examples/lighthouse-fog/output.svg" width="180">
  <img src="https://raw.githubusercontent.com/limloop/pictlang/main/examples/underwater-jellyfish/output.svg" width="180">
  <img src="https://raw.githubusercontent.com/limloop/pictlang/main/examples/lineart-space/output.svg" width="180">
</p>

*Examples generated by pictlang. See [the repository](https://github.com/limloop/pictlang/tree/main/examples) for the source code and metadata.*

## What it is

`pictlang` sends a theme and a style to a model, receives a Python
function `render()`, and runs it in a sandbox. The function uses a
small drawing DSL instead of writing SVG directly. The result is a
valid SVG file.

The DSL approach gives three things:

- **Token efficiency.** A scene in the DSL is 15–30× shorter than the
  same scene in raw SVG. Loops and functions collapse hundreds of
  repeated elements into a few lines.
- **Validation before execution.** We check the AST for "exactly one
  `render()`, no imports, no side effects" **before** running anything.
- **Safety.** The DSL is a closed set of functions. The model cannot
  emit `<script>` or external references.

## Install

```
pip install pictlang
```

Optional extras:

```
pip install "pictlang[optimize]"   # scour for SVG optimization
pip install "pictlang[socks]"      # SOCKS5 proxy support
pip install "pictlang[all]"        # everything
```

## Quick start

Create a config and set your API key:

```
pictlang init --global
# edit ~/.config/pictlang/config.json
```

Generate an image:

```
pictlang "lighthouse in the fog" --style "minimalism, three colors"
```

## Example output

```
UUID: 550e8400-e29b-41d4-a716-446655440000
SVG:  generated/valid/svg/550e8400-....svg
PY:   generated/valid/py/550e8400-....py
META: generated/valid/meta/550e8400-....json
```

The UUID is printed at the end — use it to find the files later.

## CLI

| Flag | What it does |
|---|---|
| `THEME` | What to draw (positional) |
| `--style STYLE` | How to draw it (required) |
| `--save valid\|all\|py\|svg` | What to persist (default `valid`) |
| `--optimize` / `--no-optimize` | Enable/disable SVG optimization |
| `--optimizer auto\|scour\|svgo` | Which optimizer to use |
| `--keep-original` | Save the SVG before optimization |
| `--model NAME` | Override the model |
| `--base-url URL` | Override the endpoint |
| `--proxy URL` | Proxy (http/https/socks5) |
| `--config PATH` | Path to a config file |
| `--check` | Validate config and test API connectivity |

Subcommands:

| Command | What it does |
|---|---|
| `pictlang init [--global] [--path]` | Write a template config |
| `pictlang render [uuid] [--force]` | Re-render `.svg` from `.py` without calling the API |

## Configuration

`pictlang` reads configuration from:

1. `--config PATH`, if given.
2. `./pictlang.json` in the current directory.
3. The platform user-config directory:
   - Linux: `~/.config/pictlang/config.json`
   - macOS: `~/Library/Application Support/pictlang/config.json`
   - Windows: `%APPDATA%\limloop\pictlang\config.json`
4. Built-in defaults.

See [pictlang.json.example](https://github.com/limloop/pictlang/blob/main/pictlang.json.example) for a template.

## Documentation

- [DSL reference](https://github.com/limloop/pictlang/blob/main/docs/dsl.md)
- [Architecture](https://github.com/limloop/pictlang/blob/main/docs/architecture.md)
- [Custom prompts](https://github.com/limloop/pictlang/blob/main/docs/prompt.md)

## Development

```
git clone https://github.com/limloop/pictlang.git
cd pictlang
pip install -e ".[dev]"
pytest
```

## License

Apache 2.0. See [LICENSE](https://github.com/limloop/pictlang/blob/main/LICENSE).

## Links

- [GitHub repository](https://github.com/limloop/pictlang)
- [Русская версия README](https://github.com/limloop/pictlang/blob/main/README.md)
