Metadata-Version: 2.4
Name: cr8script
Version: 1.1.0
Summary: An English-shaped scripting language for LLMs and anyone who wants quick scripts without Python's footguns.
Author: Lofi Fren
License: MIT License
        
        Copyright (c) 2026 Lofi Fren
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://cr8script.com
Project-URL: Repository, https://github.com/LofiFren/cr8script
Project-URL: Documentation, https://cr8script.com/agents.html
Keywords: scripting,language,llm,agents,interpreter,decimal,pipelines
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Interpreters
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# cr8script

An English-shaped scripting language for LLMs and anyone who wants quick
scripts without Python's footguns. One file. No build. No imports. Reads
the way you'd describe the work out loud.

Website: [cr8script.com](https://cr8script.com) -- language tour, animated
atlas, and a playable demo.

![cr8script atlas -- a mindmap of the language](mindmap.jpg)

## Quick start

```bash
python3 cr8script.py examples/tour.cr8        # the language tour
python3 cr8script.py                          # REPL
python3 cr8script.py --test                   # run the golden suite
```

Python 3.9+. No pip, no venv, no flags.

## A taste

```
let sales = [
  { product: "widget", region: "east", amount: 12.50 },
  { product: "gadget", region: "east", amount:  8.00 },
  { product: "widget", region: "west", amount: 15.00 },
  { product: "doodad", region: "east", amount: 99.00 },
]

let by_product = sales
  | group by product
  | summarize { total: sum(amount), n: length(items) }
  | sort by total descending

for each row in by_product
  show f"{row.product}: {row.total} across {row.n} order(s)"
end
```

```
doodad: 99 across 1 order(s)
widget: 27.5 across 2 order(s)
gadget: 8 across 1 order(s)
```

`examples/tour.cr8` walks the rest of the language end-to-end.

## What makes it different

- **Reads like English.** `is greater than`, `is at least`, `for each`,
  `where`, `sort by`. No `==`, `!=`, `>=`, `<=`.
- **Honest types.** No truthy/falsy. `"5" + 3` is an error. `5 is "5"` is
  an error. `if 0 then` is an error.
- **Honest decimals.** `0.1 + 0.2` is exactly `0.3`. One number type.
- **No null surprises.** Only `nothing`. Indexing a missing key returns
  `nothing`; typing the wrong field name is a hard error with a "did you
  mean" hint.
- **Immutable by default.** `let` is forever; `var` opts into change.
- **Pipelines as a first-class verb set.** `where`, `sort by`, `take`,
  `map`, `group by`, `summarize` -- bare names inside resolve to record
  fields.
- **Errors that teach.** Every error names the line, the value, and a
  one-line hint.
- **LLM-shaped diagnostics.** `--check-json` emits structured `{ line,
  message, hint }` so a model can self-correct before running.

## For language models

Three files are aimed at agents and the humans wiring them up:

- [`LLMS.md`](LLMS.md) -- condensed grammar + rules sheet. Read this first.
- [`AGENTS.md`](AGENTS.md) -- system-prompt template, tool definitions,
  and the self-correction loop spelled out for an integrator.
- [`LLM_MAP.md`](LLM_MAP.md) -- typed planning-graph layer that can sit
  between prompt and `.cr8` generation.
- [`examples/agent_loop/`](examples/agent_loop/) -- a broken `.cr8` file,
  the actual `--check-json` JSON output, and the corrected version.
  The end-to-end demo of cr8 -> diagnostics -> fix.
- [`examples/llm_map/`](examples/llm_map/) -- a first LLM-map prototype
  and rendered HTML view for the hot air balloon game.

The self-correction loop:

```bash
python3 cr8script.py --check-json file.cr8     # structured diagnostics
python3 cr8script.py file.cr8                  # run
```

## Status

v1.1. Single-file Python interpreter (`cr8script.py`, ~2.8k lines):
lexer, parser, tree-walking evaluator, REPL, static checker, ten golden
tests. The *language* is independent of Python -- only the bootstrap is.

Built-in modules: `math`, `http`, `time`, `json`, `csv`. Top-level:
`length`, `sum`, `count`, `average`, `min`, `max`, `range`, `to_text`,
`to_number`, `keys`, `type`, `assert`. Strings support `f"..."`
interpolation.

Out of scope until pulled by a real use case: regex, file I/O, dates,
modules / imports, async. **Not** on the roadmap: classes (values, not
objects).

## Layout

```
cr8script.py     single-file interpreter
LLMS.md          rules-and-grammar sheet for LLMs
AGENTS.md        system-prompt template + agent tool definitions
LLM_MAP.md       typed planning-graph format for LLM-first workflows
BENCHMARKS.md    benchmark plan focused on tokens-to-correctness
examples/
  hello, tour, load_test, make_game, make_mindmap
  agent_loop/    broken -> diagnostics -> fixed (the LLM self-correction demo)
  llm_map/       JSON planning graph + rendered HTML prototype
  api_ingest     fetch JSON, summarize, emit CSV
  validate       list of records -> { ok, errors } per item
  report_md      structured data -> markdown report
tools/
  render_llm_map.py   map JSON -> self-contained HTML/SVG view
  check_map.py        validate map JSON; check map<->code drift
testdata/        golden tests
game.html        a small playable demo (output of make_game.cr8)
```

## More

```bash
python3 cr8script.py --check file.cr8          # static checks (human output)
python3 cr8script.py --check-json file.cr8     # static checks (JSON output)
python3 cr8script.py --lex file.cr8            # token dump (debugging)
python3 cr8script.py --ast file.cr8            # AST dump  (debugging)
```
