kapy-script

The AI-native programming language. Designed for agent authorship, clean enough for anyone.

v0.1 — 239 tests, 0 failures. Production-compiled, designed for humans.

Install

# Standalone CLI
npm install -g @moikapy/kapy-script
kapy run hello.kapy

# Or as a @moikapy/kapy extension
bun install -g @moikapy/kapy
kapy install @moikapy/kapy-script

Quick Start

fn greet
  input name: string
  output string
  "Hello, {name}!"

kapy init my-project
cd my-project
kapy run src/main.kapy
# → Hello from my-project!

The Language

Functions (all async)

fn add
  input a: number
  input b: number
  output number
  a + b

Every function is async. No await, no async — I/O is implicit.

Result type

result = json.parse('{"key": "value"}')
result?      # Unwrap Ok, propagate Err
result!      # Unwrap Ok, crash on Err

Pattern matching

sealed trait Result
  case Ok(value: any)
  case Err(message: string)

match result
  Ok(v) -> v
  Err(e) -> handle_error(e)

Agents

agent ResearchAgent
  input query: string
  output Report

  tools
    search_web, read_document

  steps
    search_web(query) -> sources
    return sources

Standard library

import kapy/http        # HTTP client (get, post, put, del)
import kapy/fs           # File system (readFile, writeFile, exists)
import kapy/json         # JSON with Result types (parse, stringify)
import kapy/ai           # AI providers (OpenAI, Anthropic, Ollama)
import kapy/ai/chain     # LLM chaining (run, parallel, mapReduce)
import kapy/web/router   # HTTP server (create, get, post, listen)
import kapy/test          # Test assertions (assertEqual, assertTrue, ...)

# Escape braces in strings
text = "\{ \"hello\": 1 \}"
result = json.parse(text)

Commands

| Command | Description | |---------|-------------| | kapy run <file> | Compile and execute a .kapy file | | kapy run --watch <file> | Re-run on file changes | | kapy check <file> | Parse and type-check | | kapy fmt <file> | Format a .kapy file | | kapy fmt --check <file> | Check formatting | | kapy lint <file> | Lint for common issues | | kapy lint --strict <file> | Treat warnings as errors | | kapy test [path] | Run test declarations | | kapy init <name> | Scaffold a new project | | kapy repl | Interactive REPL |

Version Features

| Feature | v0.1 ✅ | v0.5 🔜 | |---------|---------|---------| | Functions, agents, sealed traits | ✅ | | | Pattern matching | ✅ | | | Result type with ? and ! | ✅ | | | Import, print, test | ✅ | | | HTTP, FS, JSON, AI providers | ✅ | | | Router, LLM chaining, test assertions | ✅ | | | Trait method dispatch | | 🔜 | | Exhaustiveness checking | | 🔜 | | Union & intersection types | | 🔜 | | Package manager | | 🔜 |

Stats

• 37 source files, ~7,680 lines
• 239 tests, 467 assertions
• 7 example files (hello, greet, divide, result, agent, cli-tool, web-api)

Project Structure

src/
  lexer/        Tokenizer (indentation-aware, string interpolation)
  parser/       Recursive descent parser → AST
  typechecker/  Local type inference, ADTs, version-gated warnings
  transpiler/   AST → TypeScript emitter with source maps
  runtime/      @moikapy/kapy-runtime (Result, llm, embed, print, stdlib)
  cli/          Standalone CLI (run, check, test, init, repl, fmt, lint)
  extension/    @moikapy/kapy-script kapy extension
test/           13 test files
examples/       7 .kapy example files

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.