Metadata-Version: 2.4
Name: ksb
Version: 0.2.0
Summary: KSB — token-efficient scripting language for AI agents (transpiles to Python)
Author: KSB Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/semihbalan/ksb
Project-URL: Repository, https://github.com/semihbalan/ksb
Project-URL: Issues, https://github.com/semihbalan/ksb/issues
Project-URL: Documentation, https://github.com/semihbalan/ksb#readme
Project-URL: Changelog, https://github.com/semihbalan/ksb/releases
Keywords: ksb,language,compiler,ai,agents,transpiler,llm,dsl
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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 :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# KSB — Kernel Script for Bots

**Ultra-dense scripting language for AI agents.** Fewer tokens than Python for tool scripts. Compiles to **Python 3**.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)

```ksb
@ max(a:i,b:i)->i {
  ? a>b { ^a } { ^b }
}
@ main()->i { ^ max(3,7) }
```

Dense form:

```ksb
@max(a:i,b:i)->i{?a>b{^a}{^b}}
@main()->i{^max(3,7)}
```

## Why KSB?

| Problem for agents | KSB |
|--------------------|-----|
| Long keywords burn tokens | `@` `^` `?` `*` `#` |
| Huge stdlib surface | Small agent runtime |
| Style noise | `ksb fmt` + rigid grammar |
| Silent type mistakes | `ksb check` optional types |

Paste [`KSB.md`](./KSB.md) into an agent system prompt (~400 tokens).

## Install

**From PyPI** (after first publish):

```bash
pip install ksb
ksb -V
```

**From source:**

```bash
git clone https://github.com/semihbalan/ksb.git
cd ksb
pip install -e ".[dev]"
ksb -V
```

## CLI

```bash
ksb run examples/hello.ksb
ksb run examples/match.ksb
ksb run examples/use_mod.ksb
ksb run examples/agent_kit.ksb

ksb build app.ksb -o app.py
ksb fmt app.ksb          # pretty-print to stdout
ksb fmt app.ksb -w       # write back
ksb check app.ksb        # typecheck
ksb parse app.ksb
ksb lex app.ksb
```

## Language (cheat sheet)

| Syntax | Meaning |
|--------|---------|
| `@ f(a:i)->i { ... }` | function |
| `^ e` | return |
| `= x e` | bind |
| `? c {t} {f}` | if / else |
| `* c { ... }` | while |
| `* x:xs { ... }` | for-each |
| `# e { p => v; _ => v }` | match |
| `a \| f` | pipe → `f(a)` |
| `~ fs` / `~ "lib/mathx"` | import runtime or local `.ksb` |
| `T` `F` `N` | true / false / null |

**Patterns:** `_` · literals · bind `n` · `[h,*t]` · `{ok:T, msg:m}`

**Types (optional):** `i` `f` `s` `b` `l` `m` `a`

## Runtime modules

| Module | Highlights |
|--------|------------|
| `fs` | read, write, exists, list, mkdir, remove, copy, cwd |
| `http` | get, post, put, delete, get_json, post_json |
| `json` | parse, dump |
| `sh` | run |
| `env` | get, set |
| `log` | info, err |
| `time` | now, ms, sleep, iso |
| `path` | join, dirname, basename, abs, ext |
| `cli` | args, argc, arg |
| `str` | split, join, trim, replace, contains, lower, upper |
| `tool` | ok, err, wrap — agent result shapes |

## Local modules

```ksb
// lib/mathx.ksb
@ add(a:i,b:i)->i { ^ a+b }

// app.ksb
~ "lib/mathx"
@ main()->i { ^ add(1,2) }
```

Functions from imported `.ksb` files are inlined at compile time (no `main` import).

## Architecture

```
.ksb → lex → parse → [bundle local mods] → [typecheck] → codegen → Python 3
                                              ↓
                                    ksb.runtime (agent stdlib)
```

## Development

```bash
pip install -e ".[dev]"
pytest -q
```

CI runs on every push (Python 3.10–3.13). See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/publishing.md](./docs/publishing.md) for release / PyPI.

## Topics

`ai` · `agents` · `compiler` · `language` · `llm` · `python` · `transpiler`

## License

[MIT](./LICENSE) — free for humans and agents.
