syn

syn is an experimental interpreted language focused on local AI, agents, and automation.

This repository contains the syn CLI runtime, language implementation, examples, and test suites. The current public target is a Windows-first alpha release.

Release Status

• Current version: 0.1.0-alpha
• Stability: alpha
• Compatibility: not guaranteed yet
• Primary platform: Windows

syn is already functional, but the language and runtime are still evolving. Public alpha releases are meant for testing, exploration, and feedback, not for production dependence.

What syn Includes

• lexer, parser, AST, and interpreter
• CLI commands: run, repl, version
• variables, functions, control flow, modules, arrays, and objects
• standard library for strings, collections, filesystem, HTTP, process execution, environment, time, randomness, and input
• local AI calls through Ollama
• configurable agents with memory and tool access
• automated smoke, semantics, parser, and runtime tests

Commands

syn run <file.syn> [args...]
syn repl
syn version

Quick Example

import ai

agent professor {
  role: "physics teacher"
  goal: "explain clearly"
  memory true
  model: "llama3.2:1b"
  temperature: 0.2
  tools: ["http", "fs", "process"]
}

print professor.ask("Explain entropy in one short sentence.")

Language Features

Core language:

• print
• variables
• functions with return
• if / else
• loop
• while
• for ... in ...
• break / continue
• arithmetic, comparison, and logical operators
• line comments with //

Data types:

• strings
• numbers
• arrays
• objects

Modules:

• import module_name
• relative .syn module loading

AI and agents:

• import ai
• ai "prompt"
• agent { ... }
• agent memory
• agent tools
• Ollama integration

Standard Library

Strings:

• str(x)
• num(x)
• contains(text, part)
• starts_with(text, prefix)
• ends_with(text, suffix)
• split(text, separator)
• join(array, separator)
• replace(text, search, replacement)
• trim(text)
• lower(text)
• upper(text)

Collections:

• len(value)
• push(array, value)
• pop(array)
• keys(object)
• values(object)

Filesystem:

• read_file(path)
• write_file(path, content)
• append_file(path, content)
• exists(path)
• delete_file(path)
• list_dir(path)
• mkdir(path)
• is_file(path)
• is_dir(path)
• copy_file(from, to)
• move_file(from, to)
• path_join(a, b)
• filename(path)
• parent_dir(path)

Runtime and environment:

• env(name)
• cwd()
• args()
• time()
• sleep(ms)
• rand()
• rand_int(min, max)
• input(prompt)

HTTP and process:

• http_get(url)
• http_post(url, body)
• http_request(method, url, body, headers?)
• exec(command)
• run(command)

Agents

Supported agent fields:

• role: "..." required
• goal: "..." optional
• memory true|false
• model: "..." optional
• temperature: <number>
• tools: ["fs", "http", "process"]
• tools: [{ name: "...", ... }]

Supported agent methods:

• agent.ask(prompt)
• agent.remember(text)
• agent.history()
• agent.clear()
• agent.save(path)
• agent.load(path)
• agent.tools()
• agent.http_get(url)
• agent.http_request(method, url, body, headers?)
• agent.exec(command)
• agent.run(command)
• agent.read(path)
• agent.write(path, content)
• agent.append(path, content)
• agent.list(path)

Installation

See:

• docs/INSTALLATION.md
• docs/RELEASE.md

For local source builds:

cmake -S . -B build
cmake --build build --config Debug

Binary:

build\Debug\syn.exe

Ollama

ai "prompt" and agent.ask(...) require a local Ollama server.

The runtime uses:

• http://localhost:11434
• model from SYN_OLLAMA_MODEL
• fallback model llama3.2

Recommended setup:

set SYN_OLLAMA_MODEL=llama3.2:1b

Examples

The repository includes these examples:

• examples/hello.syn
• examples/functions.syn
• examples/collections.syn
• examples/module_math.syn
• examples/modules.syn
• examples/filesystem.syn
• examples/http.syn
• examples/agents.syn
• examples/runtime.syn

Run one example:

.\build\Debug\syn.exe run examples\hello.syn

Testing

After building:

powershell -ExecutionPolicy Bypass -File tests\smoke.ps1
powershell -ExecutionPolicy Bypass -File tests\semantics.ps1
powershell -ExecutionPolicy Bypass -File tests\parser.ps1
powershell -ExecutionPolicy Bypass -File tests\runtime.ps1
ctest --test-dir build -C Debug --output-on-failure

Public Alpha Checklist

For a GitHub alpha release, this repository now includes:

• LICENSE
• CHANGELOG.md
• CONTRIBUTING.md
• docs/INSTALLATION.md
• docs/RELEASE.md
• .github/workflows/ci.yml
• scripts/package-release.ps1

License

MIT. See LICENSE.