GlyphLang

AI-first backend language that compiles to a single static binary. Designed for minimal token consumption and maximum LLM generation accuracy. ~5x fewer lines and tokens than equivalent Python/FastAPI.

When to Use

• Building REST APIs, WebSockets, or backend services with AI code generation
• Minimizing LLM token costs for backend development
• Single-file service deployment (no container orchestration needed)
• Spatial computation or self-modifying programs (Ouroboros architecture)
• Polyglot code generation (one .glyph source → Python/TypeScript output)

Quick Start

glyph init                    # Initialize project
glyph run hello.glyph         # Run server (default :3000)
glyph dev hello.glyph         # Dev server with hot reload
glyph validate src/ --ai      # Validate with JSON error output
glyph context --format compact # Project summary for AI context

Symbol Reference

Type modifiers: T! (required), T? (optional), [T] (array)

Core Patterns

CRUD API

: User {
  id: int!
  name: str!
  email: str?
}

@ GET /users -> [User] {
  % db: Database
  > db.query("SELECT * FROM users")
}

@ POST /users {
  % db: Database
  > db.insert("users", input)
}

@ GET /users/:id -> User | Error {
  % db: Database
  $ user = db.query("SELECT * FROM users WHERE id = ?", id)
  if user == null { > {error: "not found", code: 404} }
  > user
}

Pattern Matching

$ result = match code {
  200 => "OK"
  404 => "Not Found"
  n when n >= 500 => "Server Error"
  _ => "Unknown"
}

Async/Await with Combinators

@ GET /dashboard {
  $ user = async { > db.getUser(userId) }
  $ orders = async { > db.getOrders(userId) }
  > {user: await user, orders: await orders}
}

WebSocket

@ ws /chat/:room {
  on connect { ws.join(room) }
  on message { ws.broadcast_to_room(room, input) }
  on disconnect { ws.leave(room) }
}

Generics

! map<T, U>(arr: [T], fn: (T) -> U): [U] {
  $ result = []
  for item in arr { result = append(result, fn(item)) }
  > result
}

Auth + Middleware Chain

@ GET /api/profile -> User {
  + auth(jwt)
  + ratelimit(100/min)
  % db: Database
  > db.query("SELECT * FROM users WHERE id = ?", auth.user_id)
}

Type System

Project Layout

my-project/
├── main.glyph        # Entry point with routes
├── types.glyph       # Type definitions (optional)
├── utils.glyph       # Utility functions (optional)
└── .glyph/           # Build artifacts

Import modules: import "./utils" → access as utils.functionName()

AI Agent Workflow

# 1. Get project context (optimized for LLM context windows)
glyph context --format compact

# 2. Make changes, then validate
glyph validate src/ --ai    # Returns JSON errors with fix hints

# 3. Check what changed
glyph context --changed

# 4. Generate polyglot output if needed
glyph codegen main.glyph --lang typescript -o ./out

Spatial Assembly Substrate (Low-Level)

For advanced use: Ouroboros Level 3 architecture with self-modifying programs. See references/spatial-assembly.md for the full opcode reference.

Key opcodes:

Register protocol: Lowercase a-z pops stack → store. Uppercase A-Z loads register → push stack.

Common Mistakes

Performance Characteristics

• Compilation: ~867ns to static binary
• Execution: 2.95-37.6 ns/op instruction throughput
• Token savings: 23% vs FastAPI, 36% vs Flask, 57% vs Spring/Java
• Deployment: Single static binary, built-in HTTP server + DB access

References

• Spatial Assembly Opcode Reference - Full low-level instruction set
• GitHub Repository - Source, issues, discussions
• VS Code Extension - LSP + syntax highlighting