Metadata-Version: 2.4
Name: koskari
Version: 0.1.0.dev20260817
Summary: Koskari: A LISP dialect for Python
Author: Christopher O'Brien
Author-email: obriencj@gmail.com
License: GNU General Public License v3 (GPLv3)
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: repl
Requires-Dist: prompt_toolkit>=3.0; extra == "repl"
Provides-Extra: lsp
Requires-Dist: pygls>=2.0; extra == "lsp"
Requires-Dist: lsprotocol; extra == "lsp"
Provides-Extra: pygments
Requires-Dist: pygments>=2.0; extra == "pygments"
Provides-Extra: sphinx
Requires-Dist: sphinx>=7.0; extra == "sphinx"
Requires-Dist: pygments>=2.0; extra == "sphinx"
Dynamic: license-file

# <img src="docs/_static/koskari-icon.svg" height="42" align="top" alt=""> Koskari

Koskari is a LISP dialect for Python -- indent-based layout syntax, macros, and a
custom bytecode evaluator that runs on CPython.

```koskari
define greet [name]:
  print (+ "Hello, " name "!")

when-main:
  greet "world"
```

```bash
koskari hello.ki
# Hello, world!
```


## Overview

Koskari is the fourth iteration of the Sibilant idea, learning from the experiences of:
- **[spexy](https://github.com/obriencj/python-spexy)**: S-expressions compiled to Python expression strings, with `let`, `cond`, and multi-expression `lambda` grafted on. Where the reader and s-expression representation began.
- **[python-sibilant](https://github.com/obriencj/python-sibilant)**: CPython bytecode target (abandoned due to version churn)
- **[sibilant-ceval](https://github.com/obriencj/sibilant-ceval)**: Custom bytecode evaluator (blocked on call/cc implementation)

This version aims to be a perfect playground -- a language with all the useful features of Python but significantly fewer restrictions, designed to make writing code a joyous expression of will upon the computer.


## Quick Start

**Prerequisites:** Python 3.9+, a C compiler, and [uv](https://docs.astral.sh/uv/) for
the virtual-environment workflow below.

### Virtual environment

From a repository checkout:

```bash
make venv          # creates .venv and installs koskari (editable, with repl extra)
make venv-koslife  # optional: adds the koslife demo
uv run koskari     # interactive REPL
uv run koskari hello.ki
```

### Install

To install into your active Python environment instead:

```bash
pip install ".[repl]"
koskari            # interactive REPL
koskari hello.ki   # run a script
```

The `repl` extra enables syntax-highlighted REPL input via `prompt_toolkit`. Other
optional extras: `lsp`, `pygments`, `sphinx`.

See [docs/start/install-run.md](docs/start/install-run.md) for the full first-session walkthrough.


## Documentation

User documentation lives in [docs/](docs/) and builds into a Sphinx site with
`make docs`:

- **[Getting started](docs/start/overview.md)** -- install, first program, and
  two on-ramps: a [beginner track](docs/start/beginner/index.md) for readers new
  to programming and a [from-Python track](docs/start/from-python/index.md) for
  Python developers.
- **[Guide](docs/guide/index.md)** -- the shared concept spine. Each chapter is a
  quick orientation that points to the authoritative
  [concepts](docs/reference/concepts/index.md) pages for the full rules.
- **[Reference](docs/reference/index.md)** -- special forms, macros, layouts, the
  runtime library, and VM opcodes.
- **[Patterns](docs/patterns/index.md)** -- task-oriented recipes.


## Corpus and MCP server

Koskari maintains a verified example corpus under
[docs/corpus/](docs/corpus/): records carry `read` / `expand` / `eval`
verification phases, so they double as regression tests and as canonical
teaching material. The corpus is published as a Hugging Face dataset,
[obriencj/koskari](https://huggingface.co/datasets/obriencj/koskari).

A container-based **MCP server** exposes the corpus and the documentation to AI
coding assistants (Cursor, Claude Desktop, VS Code, and similar) so they can
search and author idiomatic Koskari. See
[tools/mcp/README.md](tools/mcp/README.md) for build and client setup.


## Project status

Koskari is past early bootstrap. Layout syntax and macros compile to bytecode,
the native evaluator runs programs, `.ki` modules import like Python packages,
and the CLI provides a REPL and script runner. The test suite and
[verified corpus](docs/corpus/) exercise behavior across read, expand, compile,
and eval phases.

| Area | Status |
|------|--------|
| **Language** | Layout blocks, hygienic macros, and a broad special-form surface are implemented — see the [language reference](docs/reference/index.md) |
| **Runtime** | Stackless bytecode VM: coroutines, ambient async, continuations, dynamic wind, tail-call optimization |
| **Tooling** | REPL (`repl` extra), disassembler, optional LSP, Pygments, and Sphinx integrations |
| **Self-hosting** | Core builtins and much of the library live in bootstrap `.ki` sources; the CLI runs on self-hosted `.ki`, and the self-hosted compiler is on the roadmap |

The language and APIs are still **evolving** — treat the reference as authoritative,
not frozen. Compiler and opcode inventories for maintainers live in
[design/SPECIALS.md](design/SPECIALS.md) and [design/OPCODES.md](design/OPCODES.md).
Open work is tracked in [design/TODO.md](design/TODO.md); architecture notes are
in [design/](design/).


## Development

```bash
# Lint code
make lint

# Run unit tests
make test

# Run tests across Python versions (containerized)
make test-pyversions

# Clean build artifacts
make clean

# Build user documentation (Sphinx)
make docs
```

Downstream Sphinx projects should enable
`extensions = ['koskari.extras.sphinx']` so autodoc renders `Function`, `Syntax`,
and `LayoutHandler` bindings with signatures and pattern/peer sections.


## Project Structure

The repository root is the Koskari project. Import symbols from the submodule that defines them; the top-level `koskari` package does not re-export.

```
.
├── design/                  # Design documentation (see design/README.md)
├── editors/                 # Editor syntax assets (emacs, helix, textmate)
├── examples/                # Example koskari programs (.ki files)
├── koskari/                 # Main Python package
├── koskari.pth              # Imports koskari on startup to install the .ki/.kio hooks
├── tests/                   # Test suite (mirrors package layout)
├── tools/                   # Opcode/editor regen, corpus tooling, and the MCP server
├── setup.py, setup.cfg      # Package build and tox configuration
├── Makefile                 # Build, test, and lint targets
└── Containerfile            # Runtime container image
```

### koskari package

```
koskari/
├── __init__.py              # Package init; registers import hooks
├── __main__.py              # python -m koskari entry
├── exceptions.py            # Koskari*, Reader*, Layout*, Compiler* exceptions
├── types.py                 # Value types from lib + Python predicates/helpers
├── syntax.py                # Syntax form definitions
├── hygiene.py               # Macro hygiene
├── matcher.py               # Pattern matching for special forms (Python layer)
├── builtins.py              # Builtins module placeholder (filled by bootstrap)
├── cli/                     # Console entry: Python stub, host, launchpad, and REPL
│   ├── __init__.py          # Sync entry; main() boots launch.ki via hosted_run
│   ├── host.py              # Python REPL host (prompter, eval boundary, banners)
│   ├── launch.ki            # CLI launchpad: argparse, file/command load, dispatch
│   └── repl.ki              # Interactive REPL loop
├── module.py                # Module lifecycle for .ki source files
├── importer.py              # Import hook and loader for .ki/.kio modules
├── dis.ki                   # Self-hosted disassembler for Code objects
├── bootstrap/               # Bootstrap koskari sources and loader
│   ├── *.ki                 # Core forms compiled into builtins
│   └── __init__.py          # Bootstrap loader
├── reader/                  # S-expression parser and layout block syntax
│   ├── parser.py            # Reader, SourceStream, LayoutReader
│   └── layouts/             # Layout handlers (conditionals, try, class, ...)
├── lexer/                   # Token lexer and prompt_toolkit REPL
│   ├── tokens.py, parser.py, discovery.py, highlight.py
│   └── prompt_toolkit/      # REPL integration
├── extras/                  # Optional integrations (namespace; no __init__.py)
│   ├── pygments/            # Syntax highlighting lexer
│   ├── sphinx/              # Sphinx extension and autodocumenters
│   └── lsp/                 # koskari-lsp language server
├── help/                    # In-REPL help for syntax, layouts, and tools
├── compile/                 # Compiler, bytecode fragments, special forms
│   ├── compiler.py
│   ├── helpers.py
│   ├── pragma/              # Compile-time pragma resolution
│   └── specials/            # Special form handlers
├── serialize/               # Code serialization (codex format)
└── lib/                     # C extension (native types, bytecode, evaluator)
    ├── atom.c, pair.c, namespace.c, formals.c, ref.c, values.c, ...
    ├── bytecode.c, eval.c, cont.c, dynchain.c, matcher.c, ...
    ├── dynchain/            # Dynamic extent handlers (with, wind, try, ...)
    ├── eval/                # Evaluator state machine
    └── opcode/              # Per-opcode implementations
```

### tests

```
tests/
├── lib/                     # Native extension and evaluator tests
│   └── opcode/              # Opcode-specific tests
├── compile/                 # Compiler and special-form tests
│   ├── helpers/
│   └── specials/
├── reader/                  # Parser and layout tests
│   └── layouts/
├── dis/                     # Disassembler tests
├── types/                   # Type predicate tests
├── importer/                # Import hook tests
├── lexer/                   # Lexer and prompt_toolkit tests
├── matcher/                 # Matcher tests
├── syntax/                  # Syntax form tests
├── hygiene/                 # Hygiene tests
├── help/                    # Help system tests
├── exceptions/              # Exception hierarchy tests
├── serialize/               # Serialization tests
├── cli/                     # CLI tests
├── reproducers/             # Regression reproducers
├── extras/                  # Optional integration tests (phase_extras)
│   ├── pygments/
│   ├── sphinx/
│   └── lsp/
└── native/                  # C harness and container memory tests
```


## Design Documentation

Comprehensive design documentation lives in [design/](design/). Start with [design/README.md](design/README.md) for the index. Topics include language features (special forms, operators, macros, layouts), API and types, interpreter architecture (bytecode, compiler, evaluator), and call/CC design.


## Testing

```bash
# Run Python tests (via tox)
make test

# Run native memory tests in container (requires podman or docker)
make test-native           # Basic native tests
make test-asan             # AddressSanitizer
make test-valgrind         # Valgrind memcheck

# Run tests across Python versions in containers
make test-pyversions
```


## License

GPL v3 - See [LICENSE](LICENSE) for details.


## Author

Christopher O'Brien <obriencj@preoccupied.net>
