☰

# Sesi Systems Language Documentation This document serves as a comprehensive reference for the Sesi programming language, consolidating its architecture, specifications, and usage guidelines. --- ## 1. ARCHITECTURE.md # Sesi Runtime Architecture ## Overview **Sesi** is a high-performance **Systems Language** designed for building resilient, stateful applications. It uses a tree-walking interpreter model with asynchronous host-side model execution, but no language-level `async/await` syntax in v1.2 The architecture is optimized for coordination, distributed state management, and first-class reasoning primitives. ## Component Stack ``` ┌─────────────────────────────────────────────┐ │ Sesi Program (.sesi file) │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ Lexer (src/lexer.ts) │ │ Converts source text → Tokens │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ Parser (src/parser.ts) │ │ Converts Tokens → Abstract Syntax Tree │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ Interpreter (src/interpreter.ts) │ │ Tree-walking interpreter │ │ - Evaluates expressions │ │ - Executes statements │ │ - Manages scopes/environments │ └──────┬───────────────────────┬──────────────┘ │ │ │ │ ┌──────▼──────────────┐ ┌────▼────────────────┐ │ Builtins │ │ AI Runtime │ │ (src/builtins.ts) │ │ (src/ai-runtime.ts) │ │ │ │ │ │ - print() │ │ - Gemini API calls │ │ - len() │ │ - Memory mgmt │ │ - read_file() │ │ - Structured output │ │ - write_file() │ │ - Tool calling │ │ - spawn() │ │ │ │ - exec() │ │ │ │ - time() │ │ │ │ - random() │ │ │ │ - etc. │ │ │ └─────────────────────┘ └────┬────────────────┘ │ ┌─────────▼──────────┐ │ Gemini API │ │ (@google/genai) │ └────────────────────┘ ``` ## Execution Flow ### 1. Lexical Analysis (Lexer) - **Input**: Source code string - **Process**: Character-by-character tokenization - Identifier and keyword recognition - Number and string literal parsing - Operator and delimiter recognition - Comment stripping - **Output**: Token stream **Example**: ``` Source: let x = 10 Tokens: [LET, IDENTIFIER("x"), EQUAL, NUMBER(10), EOF] ``` ### 2. Parsing (Parser) - **Input**: Token stream - **Process**: Recursive descent parsing - Statement parsing (declarations, control flow) - Expression parsing (operators, function calls, Reasoning constructs) - AST construction - Error recovery - **Output**: Abstract Syntax Tree (AST) **Example AST Node**: ```javascript { type: 'LetStatement', name: 'x', value: { type: 'Literal', value: 10, rawType: 'number' } } ``` ### 3. Interpretation (Interpreter) - **Input**: AST - **Process**: Recursive tree evaluation - Statement execution in order - Expression evaluation with proper operator precedence - Environment/scope management with lexical scoping - Blocking host-side async calls for Reasoning operations - Control flow (return, break, continue) - **Output**: Program side effects (print, Reasoning calls, etc.) ## Scope and Environment Management Sesi uses **lexical scoping** with an environment chain: ``` ┌─────────────────────────┐ │ Global Environment │ │ - Built-in functions │ │ - Global variables │ └────────┬────────────────┘ │ ┌────▼────────────────┐ │ Function Environment│ │ - Parameters │ │ - Local variables │ └────┬────────────────┘ │ ┌────▼────────────────┐ │ Block Environment │ │ - Block variables │ └─────────────────────┘ ``` ### Environment Lookup 1. Check current environment 2. Walk up parent chain until found 3. If not found anywhere, error ### Variable Assignment 1. Try to update in current scope 2. If not in current scope, try parent scopes 3. Update in the scope where variable was found ## Type System Sesi has a **dynamic type system** with runtime type checking: ``` RuntimeValue = | number | string | boolean | null | Array<RuntimeValue> | Object<string, RuntimeValue> | RuntimeFunction | RuntimeModule ``` ### Type Coercion Rules **String Concatenation** (operator `+`): ``` "Hello" + 5 → "Hello5" "Age:" 30 → "Age: 30" any + string → toString(any) + string string + any → string + toString(any) ``` **Numeric Operations**: ``` 10 + 20 → 30 "10" + 20 → "1020" (not numeric!) 10 20 → "10 20" (not numeric!) ``` **Truthiness**: ``` null → false false → false 0 → false "" → false [] → true {} → true ``` ## Reasoning Integration ### Reasoning Runtime Lifecycle 1. **Initialization**: - Load @google/genai SDK - Validate GEMINI_API_KEY environment variable 2. **During Execution**: - Parse model calls from AST - Construct prompt from string concatenation - Make async API call to Gemini - Wait for response (blocking in v1) - Validate finish reason and non-empty text - Return text response to program or throw 3. **Memory Management**: - Simple string buffers per memory ID - Append/update operations - Passed to next model call ### Model Call Flow ``` ModelCallExpression (AST) │ ├─ Evaluate prompt expression ├─ Extract configuration ("thinkingLevel", "max_tokens", "cache", etc.) ├─ Call AIRuntime.callModel() │ │ │ ├─ Create Gemini interaction request │ ├─ Send to Gemini API │ ├─ Wait for response │ ├─ Validate finish reason == STOP │ └─ Extract text from response │ └─ Return text to program or throw ``` ## Error Handling (V1) Sesi now has basic exception-style error handling in v1: 1. **Parse Errors**: Parser logs the error and synchronizes to continue parsing later statements. 2. **Runtime Errors**: Interpreter errors throw and can be caught with `try/catch`. 3. **Built-in I/O Errors**: `read_file()`, `write_file()`, and `list_dir()` throw on filesystem failure. 4. **Reasoning Errors**: `model()` throws when the SDK fails, when no text is returned. (Note: `MAX_TOKENS` finish reasons are now handled natively via an automatic async polling loop that prompts the model to continue where it left off, and therefore does not throw errors). 5. **Structured Output**: `structured_output()` attempts recovery, but currently logs parsing failures and returns `{}` if coercion still fails. ## Memory Model ### Stack - Local variables - Function parameters - Scope frames ### Heap - Arrays (dynamic) - Objects (key-value maps) - Strings (immutable) ### Reasoning Context - Conversation memory per memory ID - String buffers, not structured storage ## Performance Characteristics | Operation | Time | Notes | | --------------- | ----- | ------------------------- | | Variable lookup | O(n) | n = scope depth | | Array access | O(1) | Direct indexing | | Object access | O(1) | Map lookup | | Function call | O(1) | + body execution | | Model call | ~2-5s | Depends on Gemini latency | | Array iteration | O(n) | Foreach loop | ## Limitations (V1) - **Interpreter Single-threaded**: Each individual Sesi process is single-threaded. - **Process-level Concurrency**: Sesi uses a multi-process model via `spawn()` for concurrent task execution. - **No optimization**: No bytecode or JIT. - **Simple type system**: Runtime checking only. - **No macro system**: No compile-time code generation - **No introspection**: Can't inspect function bodies - **Limited error info**: Basic error messages ## Future Architecture (V2+) ### V2 Planned Improvements - Async/await syntax for concurrent Reasoning calls - Bytecode compiler for faster execution - Advanced error handling with stack traces - Streaming response support - Function composition and piping ### V3+ Vision - Agent framework with state machines - Knowledge base integration - Advanced memory with embedding search - Multi-agent orchestration - Custom type definitions - Macro system ## Code Organization ``` SKILLS.md # AI-agent workspace context and repo guardrails index.html # Sesi-generated landing page eslint.config.mjs # ESLint configuration dist/ # Compiled TypeScript output example.js # Helper script to run basic examples example-ai.js # Helper script to run Reasoning examples package.json # Dependencies & scripts tsconfig.json # TypeScript configuration QUICKSTART.md # Quick start guide IMPLEMENTATION_SUMMARY.md # Progress and tracking README.md # Project overview src/ ├── types.ts # Type definitions and AST ├── lexer.ts # Tokenization ├── parser.ts # AST generation ├── interpreter.ts # Execution engine ├── ai-runtime.ts # Gemini integration ├── builtins.ts # Built-in functions └── index.ts # Main entry point bin/ └── sesi.js # CLI executable main/ # Main user scripts and debugging ├── playground.sesi # Main playground script ├── start.sesi # Beginner script ├── build_website.sesi # Sesi-generated landing page builder └── tests/ # Additional syntax validation scripts examples/ ├── 01_hello.sesi # Basic example ├── 02_variables.sesi # Variables & operations ├── 03_functions.sesi # Functions with parameters ├── 04_conditionals.sesi # If/else control flow ├── 05_loops.sesi # Loops & iteration ├── 06_arrays_objects.sesi # Arrays & objects ├── 07_prompts.sesi # Prompts and string templating ├── 08_model_call.sesi # Basic Reasoning model calls ├── 09_structured_output.sesi # Schema-guided structured output with JSON recovery and empty-object fallback on failure ├── 10_code_generation.sesi # Reasoning-powered code gen ├── 11_memory_conversation.sesi # Reasoning-powered conversations ├── 12_classification.sesi # Classification ├── 13_data_pipeline.sesi # Pipeline demo ├── 14_folder_explainer.sesi # Directory parsing & reasoning └── 15_image_generation.sesi # Image generation API test docs/ ├── SPECIFICATION.md # Language spec ├── ARCHITECTURE.md # This file ├── BUILTINS.md # Built-in reference ├── IMAGE_GENERATION.md # Image generation guide ├── COMPARISON.md # Language comparison showcase ├── SYSTEMS_REASONING.md # Integrated reasoning guide ├── DISTRIBUTED_SYSTEMS.md # Swarm & coordination guide └── ROADMAP.md # Future plans tests/ └── basic.test.ts # Test suite ``` ## Workspace Context File The root-level `SKILLS.md` file is part of the practical repo architecture. It is not consumed by the Sesi runtime, but it is intended to guide AI-assisted development in this workspace. It defines repo-specific operating rules such as valid Sesi assumptions, normal execution via the global `sesi` command, and the fact that `main/` and `main/tests/` are intentional user workspace areas rather than anomalies. ## Testing Strategy **Unit Tests** (per component): ```typescript // Lexer: tokenization correctness // Parser: AST structure correctness // Interpreter: evaluation correctness // AI Runtime: Gemini integration ``` **Integration Tests**: ```typescript // Full program execution // Complex Reasoning workflows // Error handling ``` **Example Programs**: - Basic arithmetic and control flow - Functions and scoping - Arrays and objects - Reasoning model calls - Structured output parsing - Memory-based conversations ## Debugging ### Debug Output Enable debug logging (future): ```bash SESI_DEBUG=1 sesi program.sesi ``` ### AST Visualization Print AST (future): ```bash sesi --ast program.sesi ``` ### Token Stream Print tokens (future): ```bash sesi --tokens program.sesi ``` ## Conclusion Sesi's architecture prioritizes **clarity and simplicity** over performance. The tree-walking interpreter is ideal for: - Easy debugging - Simple extensions - Clear control flow - Smooth Reasoning (AI) integration As the language matures, optimizations can be added without changing the API. --- ## 2. BUILTINS.md # Sesi Built-in Functions Reference ## I/O Functions ### print(...args) Print values to standard output, separated by spaces. ```sesi print "Hello" print 42 print "Value:", 10 + 20 print [1, 2, 3] ``` **Returns**: `null` --- ## Type Functions ### type(value) -> string Get the type name of a value. ```sesi type(42) // "number" type("hello") // "string" type(true) // "bool" type(null) // "null" type([1, 2, 3]) // "array" type({}) // "object" ``` **Returns**: `string` - one of: `"number"`, `"string"`, `"bool"`, `"null"`, `"array"`, `"object"`, `"unknown"` --- ### str(value) -> string Convert any value to a string. ```sesi str(42) // "42" str(3.14) // "3.14" str(true) // "true" str([1, 2, 3]) // "[1, 2, 3]" str({ "a": 1 }) // "{'a': 1}" ``` **Returns**: `string` --- ### to_json(value) -> string Convert an array or object into a valid, formatted JSON string. ```sesi to_json({ "a": 1, "b": [1, 2] }) /* { "a": 1, "b": [1, 2] } */ ``` **Returns**: `string` (valid JSON) --- ### from_json(string) -> any Parse a valid JSON string back into a native Sesi primitive, array, or object. ```sesi let raw = "{\"a\": 1, \"b\": [1, 2]}" let obj = from_json(raw) print obj["a"] // 1 ``` **Returns**: `any` - native Sesi primitive, array, or object, or `null` if parsing fails --- ### num(value) -> number Convert a value to a number. ```sesi num("42") // 42 num("3.14") // 3.14 num(true) // 1 num(false) // 0 num("hello") // null (can't convert) ``` **Returns**: `number` or `null` if conversion fails --- ### bool(value) -> bool Convert a value to boolean. ```sesi bool(1) // true bool(0) // false bool("") // false bool("hello") // true bool([]) // true bool(null) // false ``` **Returns**: `bool` - Uses truthiness rules --- ## Collection Functions ### len(collection) -> number Get the length of a string, array, or object. ```sesi len("hello") // 5 len([1, 2, 3]) // 3 len({ "a": 1, "b": 2 }) // 2 len(null) // null (invalid) ``` **Returns**: `number` or `null` if not a collection --- ### range(n) -> array Create an array of numbers from 0 up to (but not including) n. ```sesi range(5) // [0, 1, 2, 3, 4] ``` **Returns**: `array<number>` --- ### push(array, value) -> array Add an element to the end of an array. ```sesi let arr = [1, 2, 3] push(arr, 4) print arr // [1, 2, 3, 4] ``` **Note**: Modifies array in-place and returns it. **Returns**: `array` --- ### pop(array) -> any Remove and return the last element of an array. ```sesi let arr = [1, 2, 3] let last = pop(arr) print last // 3 print arr // [1, 2] ``` **Returns**: The removed element, or `null` if array is empty --- ### join(array, separator) -> string Join array elements into a string with separator. ```sesi let arr = [1, 2, 3] join(arr, "-") // "1-2-3" join(["a", "b"], ", ") // "a, b" ``` **Returns**: `string` --- ### split(string, separator) -> array Split a string into an array by separator. ```sesi split("a,b,c", ",") // ["a", "b", "c"] split("hello world", " ") // ["hello", "world"] ``` **Returns**: `array<string>` --- ### keys(object) -> array Get all keys of an object. ```sesi let obj = { "name": "Alice", "age": 30 } keys(obj) // ["name", "age"] ``` **Returns**: `array<string>` or `null` if not an object --- ### values(object) -> array Get all values of an object. ```sesi let obj = {"name": "Alice", "age": 30} values(obj) // ["Alice", 30] ``` **Returns**: `array<any>` or `null` if not an object --- ## File System Functions ### read_file(path) -> string Read the contents of a file as a string. ```sesi let text = read_file("input.txt") print text ``` **Note**: Paths are resolved relative to the current working directory. **Returns**: `string` --- ### write_file(path, content) -> bool Write string content to a file. Overwrites the file if it exists. ```sesi let success = write_file("output.txt", "Hello, Sesi!") if success {print "File written successfully"} ``` **Note**: Paths are resolved relative to the current working directory. **Returns**: `bool` (true on success, throws on error) --- ### write_image(path, base64_content) -> bool Write base64 encoded string content as an image file. Overwrites the file if it exists. ```sesi let success = write_image("logo.png", logo_data) if success {print "Image safely stored"} ``` **Note**: Paths are resolved relative to the current working directory. **Returns**: `bool` (true on success, throws on error) --- ### list_dir(path) -> array List the contents of a directory as an array of strings. ```sesi let files = list_dir(".") print files ``` **Note**: Paths are resolved relative to the current working directory. **Returns**: `array<string>` --- ### make_dir(path) -> bool Create a new directory recursively. Returns `true` on success, `false` or throws on failure. ```sesi let success = make_dir("new_directory") if success {print "Directory created successfully"} ``` **Note**: Paths are resolved relative to the current working directory. **Returns**: `bool` (true on success, throws on error) --- ## Network Functions ### web_get(url, headers = {}) -> string Perform a synchronous HTTP GET request and return the response body as a string. ```sesi let response = web_get("https://jsonplaceholder.typicode.com/posts/1") print response ``` **Returns**: `string` --- ### web_send(url, body, headers = {}) -> string Perform a synchronous HTTP POST request with a request body and return the response as a string. ```sesi let payload = "{\"title\": \"foo\"}" let response = web_send("https://jsonplaceholder.typicode.com/posts", payload) print response ``` **Returns**: `string` --- ## System Functions ### spawn(path) -> number Launch a Sesi script as a concurrent background process. Returns the process ID (PID). ```sesi let pid = spawn("worker.sesi") print "Launched worker with PID:" pid ``` **Returns**: `number` (PID) --- ### exec(command) -> string Execute a shell command synchronously and return its output. ```sesi let files = exec("ls -la") print files ``` **Returns**: `string` (stdout) --- ### time() -> number Returns the current Unix timestamp in milliseconds. ```sesi let start = time() // ... do work ... print "Elapsed time:" time() - start "ms" ``` **Returns**: `number` --- ### multi_req(fns) -> array Concurrently execute multiple Sesi function closures or builtins in parallel and return their results as an array. ```sesi fn job1() { sleep(100) return "a" } fn job2() { sleep(100) return "b" } let results = multi_req([job1, job2]) print results // ["a", "b"] ``` **Returns**: `array<any>` containing the returned values of each function in original index order. --- ### random() -> number Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). ```sesi let rand = random() if rand > 0.5 {print "Heads"} else {print "Tails"} ``` **Returns**: `number` --- ## Math Functions ### exp(x) -> number Returns Euler's number $e$ (approx. `2.71828`) raised to the power of $x$. ```sesi exp(0) // 1.0 exp(1) // 2.718281828459045 let sigmoid = 1.0 / (1.0 + exp(0.0 - 0.5)) print sigmoid // 0.6224593312018546 ``` **Returns**: `number` --- ## Math-like Functions (v2 planned) These are not yet implemented in v1.2 but will be added: ```sesi // Planned for v2: floor(n) ceil(n) round(n) abs(n) min(a, b) max(a, b) sqrt(n) pow(a, b) sin(n), cos(n), tan(n) ``` ## Function Introspection (v2 planned) These are planned for v2: ```sesi // Get function name name(func) -> string // Get function arity (parameter count) arity(func) -> number // Check if value is a function is_function(value) -> bool ``` --- ## Collection Checks (v2 planned) ```sesi // Planned for v2: is_array(value) -> bool is_object(value) -> bool is_string(value) -> bool is_number(value) -> bool is_bool(value) -> bool is_null(value) -> bool ``` --- ## String Functions (v2 planned) ```sesi // Planned for v2: length(string) -> number // Alias for len() upper(string) -> string // Uppercase lower(string) -> string // Lowercase trim(string) -> string // Remove whitespace contains(string, substring) -> bool starts_with(string, prefix) -> bool ends_with(string, suffix) -> bool index_of(string, substring) -> number slice(string, start, end?) -> string replace(string, from, to) -> string repeat(string, count) -> string ``` --- ## Array Functions (v2 planned) ```sesi // Planned for v2: map(array, fn) -> array // Transform elements filter(array, fn) -> array // Keep matching elements reduce(array, fn, initial) -> any find(array, fn) -> any // First match includes(array, value) -> bool index_of(array, value) -> number reverse(array) -> array sort(array, compareFn?) -> array unique(array) -> array // Remove duplicates flatten(array) -> array // Flatten one level ``` --- ## Error Handling Sesi supports structured error handling via `try/catch` blocks. ```sesi try {let data = read_file("missing.txt") }catch (e) { print "Caught error:", e} ``` --- ## Tips & Tricks ### Converting values ```sesi // To string str(value) value + "" // Works for most types // To number num(string) string + 0 // Doesn't work (concatenation) // To bool bool(value) !(!value) // Double negation ``` ### Checking types ```sesi type(value) == "array" type(value) == "object" type(value) == "null" ``` ### Working with arrays ```sesi let arr = [1, 2, 3] // Length len(arr) // Last element arr[len(arr) - 1] // Add element push(arr, 4) // Remove last pop(arr) // Join join(arr, ", ") ``` ### Working with objects ```sesi let obj = { "a": 1, "b": 2 } // Get keys keys(obj) // Get values values(obj) // Check key keys(obj) contains "a" // Future: not yet supported ``` --- ## Standard Library Modules (Supported natively in v1.2+) ### std/math Includes math constants and functions: `PI`, `E`, `sin`, `cos`, `tan`, `sqrt`, `floor`, `ceil`, `abs`, `pow`, `log`, `exp`. ```sesi import { PI, E, sqrt, sin, cos } from "std/math" ``` ### std/time Includes time and sleep functions: `now()`, `sleep(ms)`. ```sesi import { now, sleep } from "std/time" ``` ### std/json Includes JSON serialization: `parse(str)`, `stringify(val)`. ```sesi import { parse, stringify } from "std/json" ``` --- ## Module Resolution (v1.2.2+) Sesi resolves localmodule imports by searching directories in priority order: | Priority | Location | Notes | | -------- | -------- | ----- | | 1 | Script's own directory | Same folder as the running `.sesi` file | | 2 | Current working directory | Where you ran `sesi` from | | 3 | `SESI_PATH` env var | Semicolon (Windows) or colon (Unix) separated paths | | 4 | `~/.sesi/lib` | Global shared library, available system-wide | ### Global Library (`~/.sesi/lib`) Place any `.sesi` module in `~/.sesi/lib` (Windows: `%USERPROFILE%\.sesi\lib`) to make it importable from any project on your system: ```powershell # Install a module globally (Windows) copy mymodule.sesi $env:USERPROFILE\.sesi\lib\ ``` ```bash # Install a module globally (Linux/Unix) cp mymodule.sesi ~/.sesi/lib/ ``` ```sesi // Now importable from any folder import {callAPI, saveImage} from "retrorender" import {GetProfile} from "profiles" import {GetGuide} from "guides" ``` ### `SESI_PATH` Environment Variable Point `SESI_PATH` to one or more additional directories for shared modules: ```powershell # Windows $env:SESI_PATH = "C:\MyLibs;C:\Projects\shared" ``` ```bash # Unix / macOS export SESI_PATH="/mylibs:/projects/shared" ``` ### Error Output If a module cannot be found in any search location, Sesi prints a detailed error showing exactly where it looked: ``` Module not found: "retrorender" Searched in: C:\MyApp C:\MyApp C:\Users\owner\.sesi\lib Tip: add a folder to SESI_PATH, or place shared modules in ~/.sesi/lib ``` --- ## Performance Notes - **print()** is unbuffered (each call flushes) - **Array operations** are O(n) for most functions - **Object operations** are O(1) for key access - **String concatenation** with + is O(n) (consider pre-allocating) --- ## Return Value Reference | Function | Return Value on Error | | ------------- | --------------------------------- | | num(value) | `null` | | len(value) | `null` | | keys(value) | `null` | | values(value) | `null` | | pop([]) | `null` | | type(value) | `"unknown"` | | str(value) | `"null"` or string representation | --- ## See Also - [Quick Start](QUICKSTART.md) - [Compare to other languages](COMPARISON.md) - [Specification](SPECIFICATION.md) - [Systems Reasoning Guide](SYSTEMS_REASONING.md) - [Image Generation](IMAGE_GENERATION.md) - [Roadmap](ROADMAP.md) - [Distributed Systems](DISTRIBUTED_SYSTEMS.md) - [Examples](../examples/) --- ## 3. COMPARISON.md # The Sesi Advantage: Why We Built a Systems & Orchestration Language Integrating Large Language Models (LLMs) into traditional applications today is painful. Standard programming languages treat AI as an external service requiring SDKs, manual prompt string concatenation, complex schema definitions, and fragile JSON parsing. **Sesi treats Reasoning as a first-class language primitive.** This document demonstrates exactly how much boilerplate and complexity Sesi eliminates compared to traditional languages like TypeScript, Python, and Go. --- ## 📊 The Cost of Boilerplate: A Data Comparison When building a simple AI-powered data pipeline (structured data extraction + conditional function calling), traditional languages spend more than half their code managing the SDK rather than executing business logic. ```mermaid xychart-beta title "Lines of Code (LOC) for an AI Data Pipeline" x-axis ["Sesi", "Python", "TypeScript", "Go"] y-axis "Lines of Code" 0 --> 140 bar [16, 45, 105, 130] ``` ### Where do the lines go? ```mermaid pie title TypeScript Pipeline Breakdown (105 LOC) "Business Logic" : 45 "Schema Declarations" : 25 "SDK & Config Boilerplate" : 15 "Manual JSON Parsing/Try-Catch" : 10 "Empty Lines" : 10 ``` ```mermaid pie title Sesi Pipeline Breakdown (16 LOC) "Business Logic" : 16 "SDK Setup (Native)" : 0 "Schema Boilerplate (Native)" : 0 "JSON Parsing (Native)" : 0 "Comments" : 0 ``` --- ## 💻 The Side-by-Side Comparison We tasked four languages with building the same script: 1. Loop over customer feedback. 2. Extract structured data (Sentiment, Category, Urgency). 3. If urgent, execute a local function (`escalateTicket`). ### 1. The Sesi Implementation (16 Lines) In Sesi, there are no SDK imports, no manual API key initializations, no complex schema builder libraries, mininmal to no comments, and no manual response parsing. ```sesi fn escalateTicket(customerId: string, reason: string) { print "ESCALATION: Customer" customerId "for" reason return "Escalation logged." } memory processingLog {"Pipeline Start:"} let rawFeedback = ["My account was charged twice for the pro plan! Fix this now!", "The new dashboard is really clean, great job team.", "I can't figure out how to export my data to CSV, it just spins."] for feedback in rawFeedback {processingLog = processingLog + "Processing:" + feedback let analysis = structured_output({sentiment: string, category: string, isUrgent: bool, summary: string}) (model("gemini-3.1-flash-lite") {"Analyze the customer feedback. Category should be Billing, UI, or Technical. Feedback:" feedback}) print "Result for:" analysis["summary"] if analysis["isUrgent"] {let resolution = tool_call(escalateTicket)(model("gemini-3.1-flash-lite") {"Call escalateTicket for customer '1234' with an exact reason based on:" feedback}) processingLog = processingLog + "Urgent action taken:" + resolution} else {processingLog = processingLog + "Logged routinely."}} print "--- Final Processing Log ---" print processingLog ``` ### 2. The TypeScript Implementation (105 Lines) TypeScript requires the official Google Gen AI SDK. Notice how much code is dedicated just to telling the model _what_ we want it to do (Schemas, Tool Declarations) and _handling_ what it gives back (JSON.parse). ```typescript import { GoogleGenAI, Type } from "@google/genai"; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); // The tool we want the model to call function escalateTicket(customerId: string, reason: string): string { console.log(`ESCALATION: Customer ${customerId} for ${reason}`); return "Escalation logged."; } // 1. Tool Declaration for the SDK (Boilerplate) const escalateToolDeclaration = { functionDeclarations: [ { name: "escalateTicket", description: "Escalate an urgent customer ticket", parameters: { type: Type.OBJECT, properties: { customerId: { type: Type.STRING, description: "ID of the customer" }, reason: { type: Type.STRING, description: "Reason for escalation" }, }, required: ["customerId", "reason"], }, }, ], }; async function processFeedback() { let processingLog = "Pipeline Start:\n"; const rawFeedback = [ "My account was charged twice for the pro plan! Fix this now!", "The new dashboard is really clean, great job team.", "I can't figure out how to export my data to CSV, it just spins.", ]; for (const feedback of rawFeedback) { processingLog += `Processing: ${feedback}\n`; // 2. Structured Data Extraction (Boilerplate Schema) const schema = { type: Type.OBJECT, properties: { sentiment: { type: Type.STRING }, category: { type: Type.STRING, description: "Billing, UI, or Technical", }, isUrgent: { type: Type.BOOLEAN }, summary: { type: Type.STRING }, }, required: ["sentiment", "category", "isUrgent", "summary"], }; const analysisResponse = await ai.models.generateContent({ model: "gemini-3.1-flash-lite", contents: `Analyze the customer feedback. Category should be Billing, UI, or Technical.\nFeedback: ${feedback}`, config: { responseMimeType: "application/json", responseSchema: schema, }, }); // 3. Manual JSON parsing and error handling let analysis; try { analysis = JSON.parse(analysisResponse.text || "{}"); } catch (e) { console.error("Failed to parse JSON"); continue; } console.log(`Result for: ${analysis.summary}`); // 4. Conditional Tool Calling & Response Handling if (analysis.isUrgent) { const escalationResponse = await ai.models.generateContent({ model: "gemini-3.1-flash-lite", contents: `Call escalateTicket for customer '1234' with an exact reason based on:\n${feedback}`, config: { tools: [escalateToolDeclaration], }, }); // 5. Manual extraction of the function call from the response object if ( escalationResponse.functionCalls && escalationResponse.functionCalls.length > 0 ) { const call = escalationResponse.functionCalls[0]; if (call.name === "escalateTicket") { const args = call.args as any; // Manual invocation of our local function using the args const resolution = escalateTicket(args.customerId, args.reason); processingLog += `Urgent action taken: ${resolution}\n`; } } else { processingLog += `Urgent action failed to trigger tool.\n`; } } else { processingLog += "Logged routinely.\n"; } } console.log("\n--- Final Processing Log ---"); console.log(processingLog); } processFeedback().catch(console.error); ``` ### 3. The Python Implementation (45 Lines) Python is cleaner than TypeScript thanks to `Pydantic`, but still requires significant setup for function calling and schema extraction. ```python import os import json from google import genai from pydantic import BaseModel client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) def escalate_ticket(customer_id: str, reason: str) -> str: print(f"ESCALATION: Customer {customer_id} for {reason}") return "Escalation logged." # BOILERPLATE: Pydantic Schema Definition class FeedbackAnalysis(BaseModel): sentiment: str category: str is_urgent: bool summary: str def process_feedback(): raw_feedback = ["My account was charged twice..."] for feedback in raw_feedback: response = client.models.generate_content( model='gemini-3.1-flash-lite', contents=f'Analyze the customer feedback.\nFeedback: {feedback}', config={'response_mime_type': 'application/json', 'response_schema': FeedbackAnalysis} ) # Parse Pydantic object analysis = FeedbackAnalysis.model_validate_json(response.text) if analysis.is_urgent: escalation_response = client.models.generate_content( model='gemini-3.1-flash-lite', contents=f"Call escalate_ticket for customer '1234' based on:\n{feedback}", config={'tools': [escalate_ticket]} ) # BOILERPLATE: Manual Tool Routing for tool_call in escalation_response.function_calls: if tool_call.name == "escalate_ticket": escalate_ticket(**tool_call.args) if __name__ == "__main__": process_feedback() ``` ### 4. The Go Implementation (130+ Lines) In Go, statically typed strictness combined with AI responses creates massive struct-defining overhead. You must define deeply nested JSON structs, handle raw byte marshaling/unmarshaling, and manually map AI function call payloads to Go reflection or manual switch statements. Sesi replaces all 130 lines of this with just its native 16 lines. --- ## Showcase 3: Distributed Orchestration Swarm This example demonstrates a complex distributed task: Spawning a background researcher, polling for completion with fault tolerance, and synthesizing results with AI. ### TypeScript (Systems Boilerplate) ```typescript import { spawn } from "child_process"; import { readFile, writeFile } from "fs/promises"; import { GoogleGenerativeAI } from "@google/generative-ai"; async function run() { const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!); const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" }); const worker = spawn("node", ["dist/index.js", "researcher.sesi"], { detached: true, }); worker.unref(); let research = null; while (!research) { try { const status = await readFile("status.txt", "utf8"); if (status.trim() === "done") { research = await readFile("output.txt", "utf8"); } } catch (e) { await new Promise((r) => setTimeout(r, 500)); } } const result = await model.generateContent(`Synthesize: ${research}`); console.log(result.response.text()); } run(); ``` ### Sesi (Agentic Systems Native) ```sesi spawn("researcher.sesi") let research = "" while research == "" { try { if read_file("status.txt") == "done" { research = read_file("output.txt") } } catch (e) { let i = 0 while i < 1000 { i = i + 1 } } } print model("gemini-3.1-flash-lite") {"Synthesize: " research} ``` **Analysis**: - **Conciseness**: Sesi achieves in 12 lines of native logic what requires 30+ lines of asynchronous boilerplate in TypeScript. - **Orchestration**: `spawn` and `model` are first-class primitives in Sesi, removing the need for manual process management and SDK initialization. - **Fault Tolerance**: Sesi's native `try/catch` handles filesystem contention with zero external library overhead. --- ## The Verdict Sesi isn't just syntactic sugar. By embedding the AI runtime directly into the parser and interpreter, Sesi understands _intent_: - You don't serialize schemas; Sesi builds the JSONSchema dynamically from your literal `{ key: type }` maps. - You don't parse responses; Sesi validates and hydrates the objects for you. - You don't route tool calls; Sesi pauses execution and handles the function reference automatically. **Less boilerplate. Fewer bugs. Faster development.** --- ## See Also - [Quickstart](../QUICKSTART.md) - [Language Specification](SPECIFICATION.md) - [Image Generation](IMAGE_GENERATION.md) - [Built-in Functions](BUILTINS.md) - [Architecture](ARCHITECTURE.md) - [Reasoning Features](SYSTEMS_REASONING.md) - [Distributed Systems](DISTRIBUTED_SYSTEMS.md) --- ## 4. DISTRIBUTED_SYSTEMS.md # Distributed Systems with Sesi Sesi is a robust systems-level environment capable of orchestrating complex, multi-process agent swarms. This document details how Sesi handles concurrency, race conditions, and distributed state. ## The "Bank Swarm" Case Study In this experiment, Sesi was used to solve a classic distributed systems problem: **Concurrent Mutual Exclusion.** ### The Challenge Five independent Sesi agents (3 Deposits, 2 Withdrawals) were launched simultaneously. All agents needed to update a single `balance.txt` file without causing data loss through race conditions. ### The Sesi Solution (The "Double-Check Write" Pattern) Sesi solves this using a high-level implementation of a filesystem lock. Even without low-level semaphores, Sesi's `try/catch` and file I/O builtins allow for an "indestructible" locking logic. #### 1. Unique Identity Each agent generates a globally unique ID using Sesi's native `time()` and `random()` builtins. ```sesi let id = "Agent_" + str(time()) + "_" + str(random()) ``` #### 2. Mutual Exclusion Loop The agent "polls" the lock file. If it finds it "unlocked," it attempts to claim it. Crucially, it then **verifies** its own claim after a micro-delay to ensure it wasn't overwritten by a simultaneous process. ```sesi while locked { if read_file("lock.txt") == "unlocked" { write_file("lock.txt", id) // Settle delay let i = 0 while i < 500 { i = i + 1 } // Verification if read_file("lock.txt") == id { locked = false } } } ``` #### 3. Critical Section Resilience Using `try/catch`, Sesi agents gracefully handle filesystem contention (when the OS prevents two processes from reading the same file at the exact same micro-second). ```sesi try { write_file("balance.txt", str(num(read_file("balance.txt")) + 100)) write_file("lock.txt", "unlocked") // Release } catch (e) { write_file("lock.txt", "unlocked") // Emergency release } ``` ## Concurrency via `spawn()` Sesi v1.1 introduced the `spawn()` builtin, allowing a single **Master Orchestrator** to launch an entire swarm of agents from one file. ```sesi // Master: Launching 5-Agent Swarm spawn("main/atm_deposit.sesi") spawn("main/atm_withdraw.sesi") spawn("main/atm_deposit.sesi") spawn("main/atm_withdraw.sesi") spawn("main/atm_deposit.sesi") ``` ## Why This Matters Sesi's approach to distributed systems is **Concise** and **Readable**. What would take dozens of lines of boilerplate in C or Java (handling threads, mutexes, and I/O exceptions) is expressed in Sesi as a series of intuitive blocks. This enables developers to build **Agent Swarms** that can work in parallel on large-scale datasets, research tasks, or code generation pipelines with guaranteed state integrity. --- ## 5. IMAGE_GENERATION.md # Image Generation in Sesi Sesi provides a native, language-level primitive for generating images using AI models. This primitive is designed to interoperate seamlessly with Sesi's file system builtins, allowing you to generate and persist images with minimal boilerplate. ## The `image` Primitive To generate an image, use the `image` keyword followed by the model name, an optional configuration block, and a prompt block. ### Syntax The syntax parallels standard `model` calls: ``` image("model-name") {"configKey": "configValue"} {"Prompt text"} ``` ### Basic Example Here is a simple example demonstrating how to generate a single image and save it to disk directly: ```sesi // 1. Define the generation prompt natively prompt request {"A simple minimalist company logo for a bakery"} // 2. Call the image generation primitive let imageData = image("gemini-3.1-flash-image-preview") {"ratio": "1:1", "size": "1K"} {request} // 3. Write the payload to disk try {let success = write_image("bakery_logo.png", imageData) if success {print "Saved bakery_logo.png successfully."}} catch (e) {print "Failed to generate image:" print e} ``` <img src="bakery_logo.png" alt="Bakery Logo" style="width:480px;"> ### Advanced Example: Batch Asset Generation Workflow Here is a practical script demonstrating how to iterate over a data set, generate assets, and save them to a specific directory. This is useful for building automated pipelines like generating UI placeholders or product catalog images. ```sesi // Set up output directory let outputDir = "assets/products/" make_dir(outputDir) let products = ["coffee_mug", "desk_lamp", "notebook"] // Iterate through the list and generate a file for each for product in products {print "Generating asset for:" product // Construct the instruction for the model prompt request {"A clean studio presentation photograph of a " product " on a solid white background."} prompt filename { outputDir product ".png" } try {let imageData = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": "1K"} {request} // Attempt local file write let success = write_image(filename, imageData) if success {print "Saved:" filename}} catch (e) {print "Failed processing" product ":" print e}} print "Asset generation complete." ``` <img src="coffee_mug.png" alt="Coffee Mug" style="width:340px;"> <img src="desk_lamp.png" alt="Desk Lamp" style="width:340px;"> <img src="notebook.png" alt="Notebook" style="width:340px;"> ## Configuration Options When configuring the `image` call (specifically for models like `gemini-3.1-flash-image-preview`), the configuration block maps directly to backend SDK capabilities: - `"ratio"`: The aspect ratio of the image (e.g., `"1:1"`, `"16:9"`, `"9:16"`). - `"size"`: Dimensional sizing constraints (Must be `"512"`, `"1K"`, `"2K"`, or `"4K"`). - `"temperature"`: *Will be deprecated in Gemini 3.x+, use thinkingLevel instead.* — controls variance. ## File I/O Integration: `write_image` The `image()` call evaluates to a `string` (specifically, base64-encoded image data). To convert this into a standard image file on disk, you must use the `write_image(path, base64_content)` builtin. **Important:** Do *not* use `write_file` for image payloads—`write_image` is explicitly implemented in the Sesi engine (`src/builtins.ts`) to handle `Buffer.from(content, 'base64')` decoding for writing safe binary formats. --- ## Passing Images as Input (v1.2+) Both `model()` and `image()` accept local image files as visual input via the `images` config key. The runtime reads each file from disk, base64-encodes it, and attaches it as an inline data part alongside the prompt. This enables vision tasks such as image description, comparison, OCR, style transfer, and reference-guided generation. ### Supported Formats `.jpg` / `.jpeg`, `.png`, `.gif`, `.webp`, `.bmp` ### Syntax ``` model("model-name") {images: pathExpr} {prompt} image("model-name") {images: pathExpr} {prompt} ``` `pathExpr` is any Sesi expression that evaluates to a `string` (single file) or an `array` of strings (multiple files). ### Single Image — Describe a File ```sesi let caption = model("gemini-3-flash-preview") {images: "shots/frame_01.jpg"} {"Describe what is happening in this photograph in one paragraph."} print caption ``` ### Multiple Images — Side-by-Side Comparison ```sesi let frames = ["take_a.jpg", "take_b.jpg"] let notes = model("gemini-3-flash-preview") {images: frames} {"These are two alternate takes of the same scene. List the differences in composition and lighting."} print notes ``` ### Dynamic Path from a Variable ```sesi let src = "scans/print_neg_04.png" let reading = model("gemini-3-flash-preview") {images: src} {"Read and transcribe all visible text in this image."} write_file("output/transcription.txt", reading) print "Transcription saved." ``` ### Reference-Guided Image Generation Pass a reference image to an image-generation model to ground its output. ```sesi let ref = "references/grille_detail.jpg" let render = image("gemini-3.1-flash-image-preview") {images: ref, ratio: "16:9"} {"Render a full front elevation in the same visual style as the reference."} write_image("output/elevation.png", render) print "Render saved." ``` ### Pipeline: Batch Description from a Directory ```sesi let dir = "frames/" let files = list_dir(dir) for f in files { prompt p {dir f} let desc = model("gemini-3.1-flash-lite") {images: p} {"Describe this frame in one sentence."} print f desc } ``` ### Config Reference When used inside `model()` or `image()` config blocks, `images` is resolved at runtime — it is **not** a static string key passed to theGemini SDK. All other config keys (`thinkingLevel`, `max_tokens`, `ratio`, `size`, etc.) work alongside it normally. | Key | Accepted Value | Notes | |-----|---------------|-------| | `images` | `string` or `array<string>` | One or more local file paths. Resolved relative to `process.cwd()`. | > **Note:** Multimodal input requires a vision-capable model (e.g. `gemini-3-flash-preview`, `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview`). Image-generation models that accept reference images are listed in their respective model documentation. --- ## 6. IMPLEMENTATION_SUMMARY.md # Sesi Language - Complete Implementation Summary ## 📋 Overview **Sesi** is a high-performance **Systems Language** designed for building resilient, stateful applications. It provides first-class primitives for process management and filesystem orchestration, while integrating reasoning as a first-class execution primitive. Unlike traditional languages that rely on external SDKs for AI interaction, Sesi treats reasoning as a native language construct, enabling developers to build context-aware systems with minimal boilerplate. ## 🎯 Design Philosophy Sesi follows these core principles: 1. **Reasoning as a Primitive**: Reasoning calls aren't library functions—they're language constructs with dedicated syntax. This allows for deep integration with the interpreter's environment and type system. 2. **Practical Over Perfect**: Focus on what developers actually need, not theoretical completeness. 3. **Transparency Over Magic**: Explicit reasoning calls with clear costs and latency. 4. **Simplicity First**: Tree-walking interpreter for clarity and maintainability. 5. **Type Safety with Flexibility**: Static types for normal code, runtime checking for reasoning outputs. ## 📁 Complete Project Structure ``` Sesi/ ├── SKILLS.md # Workspace context and repo guardrails ├── index.html # Sesi-generated systems landing page ├── eslint.config.mjs # ESLint configuration ├── example.js # Helper script to run basic examples ├── example-ai.js # Helper script to run reasoning examples ├── README.md # Project overview ├── QUICKSTART.md # Getting started guide ├── package.json # Dependencies & scripts ├── tsconfig.json # TypeScript configuration ├── dist/ # Compiled TypeScript output │ ├── src/ # Source code │ ├── types.ts # Type definitions & AST nodes (400+ lines) │ ├── lexer.ts # Tokenization (350+ lines) │ ├── parser.ts # Recursive descent parser (700+ lines) │ ├── interpreter.ts # Tree-walking interpreter (600+ lines) │ ├── builtins.ts # Built-in functions (250+ lines) │ ├── ai-runtime.ts # Integrated reasoning integration (120+ lines) │ └── index.ts # Entry point (30+ lines) │ ├── bin/ │ └── sesi.js # CLI executable │ ├── main/ # Playgrounds & debugging │ ├── playground.sesi # Main playground script │ ├── start.sesi # Beginner script │ ├── build_website.sesi # Sesi-powered systems site generator │ └── tests/ # Additional syntax validation scripts │ ├── docs/ │ ├── SPECIFICATION.md # Complete language spec (600+ lines) │ ├── ARCHITECTURE.md # Runtime & system design (400+ lines) │ ├── BUILTINS.md # Built-in functions reference (450+ lines) | ├── IMAGE_GENERATION.md # Image generation guide (>100 lines) │ ├── SYSTEMS_REASONING.md # Integrated reasoning guide (500+ lines) |. ├── DISTRIBUTED_SYSTEMS.md # Swarm & coordination guide (>100 lines) │ └── ROADMAP.md # V2-V4+ development plan (400+ lines) │ ├── examples/ │ ├── 01_hello.sesi # Hello World │ ├── 02_variables.sesi # Variables & operations │ ├── 03_functions.sesi # Functions with parameters │ ├── 04_conditionals.sesi # If/else control flow │ ├── 05_loops.sesi # While, for, for-in loops │ ├── 06_arrays_objects.sesi # Collections │ ├── 07_prompts.sesi # Reasoning blocks │ ├── 08_model_call.sesi # Basic reasoning calls │ ├── 09_structured_output.sesi # Type-safe reasoning responses │ ├── 10_code_generation.sesi # Systems logic generation │ ├── 11_memory_conversation.sesi # Multi-turn stateful reasoning │ ├── 12_classification.sesi # Systems classification loop │ ├── 13_data_pipeline.sesi # Complete systems pipeline │ ├── 14_folder_explainer.sesi # Directory parsing & reasoning │ ├── 15_image_generation.sesi # Image generation API test │ ├── 16_modules.sesi # Modules & std library namespaces │ ├── 17_http_client.sesi # Network GET/POST client │ └── 18_parallel_requests.sesi # Parallel requests concurrency │ └── tests/ └── basic.test.ts # Test suite ``` ## 🔧 Technology Stack | Component | Technology | Rationale | | --------- | ------------------------ | ---------------------------------------- | | Language | TypeScript | Type safety, IDE support, easy debugging | | Runtime | Node.js 18+ | Wide availability, async support | | Reasoning | Gemini 3.1 | Latest models, 1M token context, fast | | SDK | @google/genai | Official, well-maintained, async-first | | Parser | Recursive descent | Simple, readable, extensible | | Execution | Tree-walking interpreter | Easy to understand and modify | | Testing | Typescript | Standard Node.js test framework | **Why this stack?** - **Tree-walking interpreter over bytecode**: Easier to understand, modify, and debug. No premature optimization. - **TypeScript over JavaScript**: Catch errors early, better IDE support, self-documenting code. - **Recursive descent over other parsers**: Handles the grammar perfectly, easy to add language features. - **Gemini over other models**: Excellent instruction following, function calling support, cost-effective. ## 🌟 Language Features (V1) ### Core Language ✅ **Variables & Bindings** ```sesi let x = 10 let PI = 3.14159 let y // null initially ``` **Functions** ```sesi fn add(a: number, b: number) -> number {return a + b} fn greet(name: string = "World") {print "Hello, " + name} ``` **Control Flow** ```sesi if condition { ... } else { ... } while condition { ... } for x = 0 to 10 { ... } for item in array { ... } try { ... } catch (e) { ... } ``` **Operators** - Arithmetic: `+`, `-`, `*`, `/`, `%` - Comparison: `==`, `!=`, `<`, `>`, `<=`, `>=` - Logical: `&&`, `||`, `!` - Assignment: `=` **Data Types** - Primitives: `number`, `string`, `bool`, `null` - Collections: `array<T>`, `object<T>` - Functions: First-class values - Union types: `T | U` - Optional: `T?` **Scoping** - Lexical scoping with environment chain - Block scope for loops/conditionals - Closure support ### Integrated Reasoning Features ✅ **Prompt Blocks** ```sesi prompt greeting {"Hello, " name "!"} ``` **Reasoning Calls** ```sesi let response = model("gemini-3-flash-preview") {"temperature": 0.7, "max_tokens": 1000} {"Your prompt here"} ``` **Structured Output** ```sesi let result = structured_output({field1: string, field2: number})(model("gemini-3.1-flash-lite") {"Your prompt here"}) ``` **Image Generation** ```sesi let logo = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": 512} {"Your prompt here"} write_image("logo.png", logo) ``` **Temporal Context Injection** ✅ Every reasoning call automatically includes the current UTC date and time in its context, providing the system with a native sense of "now." **Implicit Statement Termination** ✅ Expressions ending in `}` (such as prompt blocks or reasoning calls) no longer strictly require a newline or semicolon to terminate, allowing for cleaner one-liner syntax. **Async Polling for MAX_TOKENS** ✅ The AI runtime natively polls the model if it hits a `MAX_TOKENS` finish reasoning block, automatically appending previous chunks and prompting the model to continue exactly where it left off, seamlessly synthesizing long responses. **Tool Calling** ```sesi let result = tool_call(functionName)(model(gemini-3.1-flash-lite) {"Your prompt here"}) ``` **Memory** ```sesi memory conversation {"Initial context"} conversation = conversation + "User: How are you?" print("Current Conversation Memory:") print((conversation) // Demonstrate using the memory in a model call print("Calling model with memory context...") let response = model("gemini-3-flash-preview") {conversation} print("Reasoning Response:", response) ``` ## 🛠️ Built-in Functions ### I/O - `print(...args)` - Output to stdout - `read_file(path)` - Read file contents - `write_file(path, content)` - Write file contents - `write_image(path, content)` - Write base64 image data to file - `from_json(path)` - Read a JSON file - `list_dir(path)` - List directory contents - `spawn(path)` - Launch concurrent background process - `exec(command)` - Synchronous shell execution - `time()` - Unix timestamp (ms) - `random()` - Random number (0-1) ### Type Functions - `type(value)` - Get type name - `str(value)` - Convert to string - `to_json(value)` - Convert to JSON string - `num(value)` - Convert to number - `bool(value)` - Convert to boolean ### Collection Functions - `len(collection)` - Get length - `push(array, value)` - Add element - `pop(array)` - Remove element - `join(array, sep)` - Join to string - `split(string, sep)` - Split to array - `keys(object)` - Get keys - `values(object)` - Get values - `range(n)` - Create range array ### Network - `web_get(url, headers)` - Perform HTTP GET request - `web_send(url, body, headers)` - Perform HTTP POST request ### Concurrency - `multi_req(fns)` - Concurrently execute multiple closures/functions ## 📊 Implementation Statistics | Metric | Value | | ------------------- | ------ | | Total lines of code | ~3,000 | | Source files | 7 | | Documentation pages | 5 | | Example programs | 15 | | Built-in functions | 23 | | Supported operators | 20+ | | AST node types | 30+ | | Token types | 50+ | ## 🚀 Getting Started ### Installation ```bash cd Sesi npm install npm run build npm install -g . ``` ### Run Example ```bash sesi examples/01_hello.sesi ``` ### Run with Reasoning ```bash sesi examples/08_model_call.sesi ``` ### Run Tests ```bash npm test ``` ## 💡 Key Implementation Details ### Lexer Design - Character-by-character scanning - Keyword recognition - String/number literal parsing - Comment stripping - Position tracking for error messages ### Parser Design - Recursive descent parsing - Expression precedence (11 levels) - Error recovery via synchronization - Full AST construction - Support for all language constructs ### Interpreter Design - Tree-walking evaluation - Environment chain for scoping - Async support for reasoning calls - Control flow exceptions (return, break, continue) - Built-in function dispatch ### Reasoning Runtime Design - Async Gemini API calls (via @google/genai) - Response parsing and validation - Memory buffer management - Structured output JSON extraction with automatic schema simplification - Automatic injection of current UTC date/time context - Graceful error handling ## 📚 Documentation Coverage ✅ **SPECIFICATION.md** (600+ lines) - Complete language grammar - All language constructs - Type system details - Built-in functions - Runtime semantics - Module system design ✅ **ARCHITECTURE.md** (400+ lines) - Component stack diagram - Execution flow explanation - Scope management - Type system details - Reasoning integration flow - Error handling strategy - Performance characteristics ✅ **BUILTINS.md** (450+ lines) - Complete function reference - Usage examples - Return value documentation - Performance notes - Standard library plans ✅ **SYSTEMS_REASONING.md** (500+ lines) - Systems reasoning overview - Prompt blocks explained - Model call configuration - Structured output guide - Memory system details - Practical patterns - Error handling - Performance tips ✅ **ROADMAP.md** (400+ lines) - V1.0 features (Complete) - V1.1 improvements (Complete) - V2.0 async & advanced reasoning (Q3-Q4 2026) - V3.0 systems framework - V4.0+ vision - Community involvement - Backwards compatibility ## 🎓 Example Programs | File | Demonstrates | | --------------------------- | ------------------------------- | | 01_hello.sesi | Basic print | | 02_variables.sesi | Variables and operations | | 03_functions.sesi | Functions, parameters, defaults | | 04_conditionals.sesi | If/else logic | | 05_loops.sesi | While, for, for-in | | 06_arrays_objects.sesi | Collections and indexing | | 07_prompts.sesi | Reasoning blocks | | 08_model_call.sesi | Basic reasoning calls | | 09_structured_output.sesi | Schema-guided output | | 10_code_generation.sesi | Reasoning code generation | | 11_memory_conversation.sesi | Multi-turn with memory | | 12_classification.sesi | Reasoning classification loop | | 13_data_pipeline.sesi | Complete pipeline | | 14_folder_explainer.sesi | Directory parsing & reasoning | | 15_image_generation.sesi | Image generation API test | | 16_modules.sesi | Imports/exports & std namespaces| | 17_http_client.sesi | HTTP GET and POST operations | | 18_parallel_requests.sesi | Parallel request concurrency | ## ✨ Unique Features 1. **First-class Reasoning Integration**: Not a library, but language syntax 2. **Prompt Blocks**: Composable, type-checked message templates 3. **Structured Output**: Get typed responses from models 4. **Memory Construct**: Native multi-turn conversation support 5. **Simple Yet Complete**: All core features in ~3K lines of code 6. **Well Documented**: 2000+ lines of documentation 7. **Production Ready (for v1)**: Error handling, examples, tests ## 🔮 Future Directions ### V2: Async & Advanced Logic - Async/await for concurrent reasoning calls - Streaming responses - Advanced memory with embeddings - finally blocks, custom error types, retry policies, timeout handling, and structured Reasoning error recovery ### V3: Systems Framework - System state machines - Multi-process collaboration - Knowledge base integration - RAG (Retrieval-Augmented Generation) ### V4+: Scale & Optimization - Bytecode compilation - JIT compilation - Distributed execution - Cross-model orchestration ## 🧪 Testing Strategy **Component Testing** - Lexer: Token stream correctness - Parser: AST structure correctness - Interpreter: Evaluation correctness **Integration Testing** - Example programs run successfully - Reasoning features work with real API - Error handling is graceful **Example Coverage** - 15 complete example programs - Covers all major language features - Demonstrates reasoning integration - Real-world use cases ## 🎯 Design Decisions Explained ### Why a tree-walking interpreter? - **Simplicity**: Easy to understand, modify, extend - **Debugging**: Can print AST and execution steps - **Iteration**: No compilation overhead, fast development - **Good enough**: Performance is adequate for v1 ### Why recursive descent parser? - **Clarity**: Each grammar rule is a function - **Flexibility**: Easy to add new constructs - **Error recovery**: Can synchronize after errors - **No dependencies**: No external parser generators ### Why Gemini specifically? - **Instruction following**: Excellent at understanding prompts - **Function calling**: Built-in tool use support - **Context window**: 1M tokens for long documents - **Cost**: Competitive pricing - **Availability**: Easy to use via official SDK ### Why does v1.2+ support a module system? - **Organization**: As Sesi programs grew, having a single-file system became limiting. Local module imports/exports and standard libraries (`std/math`, `std/time`, `std/json`) are natively supported in v1.2+. ### Why does v1.2+ support parallel execution? - **Concurrency**: While the interpreter remains tree-walking and single-threaded for simplicity, native concurrency is supported via the parallel request executor `multi_req(array<function>)`, executing asynchronous operations physically in parallel. ## 📖 Learning Path 1. **Start**: [QUICKSTART.md](QUICKSTART.md) - Get running in 5 minutes 2. **Basics**: examples/01-06 - Core language features 3. **Prompts**: examples/07 - Prompt blocks 4. **Reasoning**: examples/08-12 - Reasoning feature exploration 5. **Specification**: [SPECIFICATION.md](docs/SPECIFICATION.md) - Complete grammar 6. **Advanced**: [SYSTEMS_REASONING.md](docs/SYSTEMS_REASONING.md) - Patterns and best practices 7. **Builtins**: [BUILTINS.md](docs/BUILTINS.md) - Built-in functions 8. **Image Generation**: [IMAGE_GENERATION.md](docs/IMAGE_GENERATION.md) examples/15 - Generating images natively 9. **Architecture**: [ARCHITECTURE.md](docs/ARCHITECTURE.md) - How it works 10. **Roadmap**: [ROADMAP.md](docs/ROADMAP.md) - Future vision ## 🤝 Contributing Path 1. Report bugs with minimal examples 2. Suggest language features via RFCs 3. Add built-in functions 4. Improve documentation 5. Submit example programs 6. Help with test coverage ## 🎁 What's Included - ✅ Complete interpreter (3000+ lines of TypeScript) - ✅ Full language specification (600+ lines) - ✅ Architecture documentation (400+ lines) - ✅ API reference (450+ lines) - ✅ Systems reasoning guide (500+ lines) - ✅ Development roadmap (400+ lines) - ✅ 15+ example programs - ✅ CLI executable - ✅ Test suite - ✅ Quick start guide ## 📝 Next Steps 1. **Build and install**: `npm install && npm run build && npm install -g .` 2. **Try examples**: `sesi examples/01_hello.sesi` 3. **Set up Reasoning**: Set GEMINI_API_KEY in `.env` 4. **Explore Reasoning**: `sesi examples/08_model_call.sesi` 5. **Read docs**: Start with SPECIFICATION.md 6. **Write programs**: Create your own .sesi files 7. **Check roadmap**: See where language is headed ## 🚀 Philosophy > "Sesi demonstrates that systems-level logic and integrated reasoning can be unified into a single, elegant language primitive, eliminating the boilerplate of traditional AI development." The language is designed to evolve. V1 provides a solid foundation. V2+ adds power. The architecture supports this gracefully without breaking existing programs. --- **Status**: ⏳ Ongoing V1.2 implementation **Ready for**: Distributed systems orchestration and prototypes **Not ready for**: Massive-scale production (until v2.0 bytecode) **Next milestone**: V2.0 (Async & advanced reasoning) Sesi is an experiment in language design. Use it to learn, explore, and evolve what integrated reasoning will become. --- For more information, see the documentation in `docs/` and examples in `examples/`. --- ## 7. QUICKSTART.md # Quick Start Guide: Sesi Programming Language ## Installation You can install Sesi in three ways: via npm (easiest for Node.js users), downloading a standalone executable (no Node.js required), or building from source. ### Option 1: Install via npm (Recommended) If you already have Node.js installed, you can install Sesi globally with a single command: ```bash npm install -g sesi ``` ### Option 2: Standalone Executable If you don't want to install Node.js, you can download a standalone binary: 1. Go to the [GitHub Releases](https://github.com/Misterscan/Sesi/releases) page. 2. Download the executable for your OS (`sesi-win.exe`, `sesi-macos`, or `sesi-linux`). 3. Add the folder containing the executable to your system's `PATH` variable, or run it directly from the folder (`.\sesi-win.exe`). ### Option 3: Build from Source (For Contributors) **Prerequisites:** Node.js 18+ and npm ```bash git clone https://github.com/Misterscan/Sesi.git cd Sesi npm install # Compile the TypeScript files npm run build # Link the `sesi` command globally to your local source folder npm install -g . ``` ### Build Native Installers Windows MSI installer: ```bash npm run build:installer ``` macOS PKG installer (run on macOS): ```bash npm run build:mac:installer ``` The generated installer files are written to `releases/`. ### Run a program Once Sesi is installed, you can run Sesi files globally: ```bash sesi main/start.sesi ``` ### Run Tests For devs working on Sesi, you can verify your backend edits with the built-in test suite: ```bash npm test ``` ## Your First Program Create a file called `hello.sesi`: ```sesi print "Hello, Sesi!" ``` Run it: ```bash sesi hello.sesi ``` ## Basic Syntax ### Variables ```sesi let x = 10 let name = "Alice" let score = 95.5 print x print name print score ``` ### Functions ```sesi fn add(a: number, b: number) {print a + b} add(5, 3) // 8 ``` ### Control Flow ```sesi let age = 25 if age >= 18 {print "Adult"} else {print "Minor"} ``` ### Loops ```sesi // While loop let i = 0 while i < 5 { print i i = i + 1 } // For loop for j = 0 to 5 {print j} // For-in loop for item in [1, 2, 3] {print item} ``` ### Arrays & Objects ```sesi let numbers = [1, 2, 3, 4, 5] print numbers[0] // 1 print len(numbers) // 5 let age = numbers[4] * 5 // 5 * 5 = 25 let person = {"name": "Alice", "age": age} print person["name"] "is" person["age"] "years old." // "Alice is 25 years old." ``` ## Reasoning Features ### Requiring Gemini API To use Reasoning features, set up your API key: ```bash export GEMINI_API_KEY="your-api-key-here" ``` Or you can set it up in an `.env` file: ```env GEMINI_API_KEY="your-api-key-here" ``` Get your key from [Google AI Studio](https://aistudio.google.com/app/apikey). ### Simple Model Call Reasoning features allow passing configuration options via a block format before the prompt. ```sesi let response = model("gemini-3-flash-preview") {"temperature": 0.8, "max_tokens": 1000} {"What is 2 + 2?"} print response ``` ### Prompts ```sesi let name = "Developer" prompt greeting {"Hello, " name "! " "How are you today?"} print greeting ``` ### Structured Output ```sesi let analysis = structured_output({sentiment: string, score: number})(model("gemini-3.1-flash-lite") {"Analyze sentiment of: This product is great!"}) print "Sentiment: " analysis["sentiment"] print "Score: " analysis["score"] ``` ### Image Generation Like `model`, the `image` command takes configuration parameters. ```sesi let logo = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": 512, "temperature": 0.3, "max_tokens": 512} {"make a beautiful logo for the word Sesi"} write_image("logo.png", logo) print "Generated image successfully!" ``` ### Memory & Conversation ```sesi memory chat {"You are helpful."} let response = model("gemini-3-flash-preview") {chat "User: Hello!"} print response chat = chat "Assistant:" response ``` ### Concurrent Swarms Sesi can orchestrate multiple concurrent scripts using the `spawn()` builtin. ```sesi // master.sesi spawn("worker_1.sesi") spawn("worker_2.sesi") print "Both workers are now running concurrently." ``` --- ## Built-in Functions ### I/O ```sesi print value // Print to stdout read_file(path) // Read a file as text from_json(path) // Read a JSON file write_file(path, content) // Write text to a file write_image(path, content) // Write base64 encoded image to a file list_dir(path) // List directory contents spawn(path) // Launch concurrent background process exec(command) // Synchronous shell execution time() // Unix timestamp (ms) random() // Random number (0-1) ``` ### Type Checking ```sesi type(value) // Get type name str(value) // Convert to string to_json(value) // Convert to valid JSON string num(value) // Convert to number bool(value) // Convert to boolean ``` ### Collections ```sesi len(array) // Array/string length push(array, item) // Add to array pop(array) // Remove from array join(array, sep) // Join array into string split(string, sep) // Split string to array keys(object) // Get object keys values(object) // Get object values range(n) // Create [0, 1, ..., n-1] ``` ### Network & Concurrency ```sesi web_get(url, headers = {}) // Natively fetch from URL via HTTP GET web_send(url, body, headers = {}) // Natively post body to URL via HTTP POST multi_req(array<function>) // Run multiple tasks/requests physically in parallel ``` ### Standard Library Modules Standard library features are available natively in **v1.2.0+** using imports: ```sesi import { PI, sqrt } from "std/math" import { sleep, now } from "std/time" import { stringify, parse } from "std/json" ``` ## Running Examples Try the included examples: ```bash # Basic examples sesi examples/01_hello.sesi sesi examples/02_variables.sesi sesi examples/03_functions.sesi sesi examples/04_conditionals.sesi sesi examples/05_loops.sesi sesi examples/06_arrays_objects.sesi # Reasoning examples (automatically loads .env for Gemini API key) sesi examples/08_model_call.sesi sesi examples/09_structured_output.sesi sesi examples/10_code_generation.sesi sesi examples/11_memory_conversation.sesi sesi examples/12_classification.sesi sesi examples/13_data_pipeline.sesi sesi examples/14_folder_explainer.sesi # Image generation example sesi examples/15_image_generation.sesi # Advanced Version 1.2 features sesi examples/16_modules.sesi sesi examples/17_http_client.sesi sesi examples/18_parallel_requests.sesi ``` ## Common Patterns ### Processing Arrays ```sesi let numbers = [1, 2, 3, 4, 5] // Iterate for n in numbers {print n} // Build new array let doubled = [] for n in numbers {push(doubled, n * 2)} print doubled // [2, 4, 6, 8, 10] ``` ### String Operations ```sesi let text = "hello world" // Concatenation let greeting = "Hello," + "World!" // Length let len = len(text) // Uppercase/lowercase (v2+) // let upper = upper(text) // let lower = lower(text) // Split and join let words = split(text, " ") let rejoined = join(words, "-") ``` ### Reasoning Classification ```sesi fn classify(item: string) {print model("gemini-3-flash-preview") {"Classify as: FRUIT, VEGETABLE, or GRAIN. Item: " item}} classify("apple") classify("carrot") classify("wheat") ``` ## Debugging Tips ### Print Intermediate Values ```sesi fn complex(x: number) { let step1 = x * 2 print "Step 1:" str(step1) let step2 = step1 + 10 print "Step 2:" str(step2) } complex(5) ``` ### Check Types ```sesi let value = "hello" print type(value) // "string" if type(value) == "string" {print "It's a string!"} ``` ### Validate Model Responses ```sesi let response = model("gemini-3-flash-preview") {"Respond with YES or NO"} if response == "" {print "Error: no response"} else if len(response) > 100 {print "Warning: response too long"} else {print "Response: " response} ``` ## Performance Considerations - **Model calls are blocking**: Each model() call waits for the API response - **Token usage**: Larger prompts use more tokens and cost more - **Use appropriate models**: gemini-3.1-flash-lite for most tasks, gemini-3.1-pro-preview for complex reasoning - **Batch operations**: Ask Reasoning to process multiple items in one call instead of looping ## Next Steps 1. **Read the spec**: [SPECIFICATION.md](docs/SPECIFICATION.md) 2. **Learn about reasoning**: [SYSTEMS_REASONING.md](docs/SYSTEMS_REASONING.md) 3. **Understand architecture**: [ARCHITECTURE.md](docs/ARCHITECTURE.md) 4. **Check roadmap**: [ROADMAP.md](docs/ROADMAP.md) 5. **Study examples**: [examples/](examples/) ## Getting Help Sesi comes with an advanced, built-in **Interactive RAG Co-Pilot** right in your command line! Instead of static help messages, you can query Sesi directly about how to use any statement, standard library, or architectural pattern: ```bash # Ask the Sesi Co-Pilot for help directly sesi -help "how do I parse a JSON string?" sesi --help "explain structured_output and give an example" sesi -h "how to spawn background processes?" ``` The co-pilot will dynamically index and train on Sesi's native repository database and retrieve full RAG context from our standard specification docs to generate a syntactically correct, 100% accurate, conversational answer in real-time! You can also: - Check documentation in [docs/](docs/) - Review examples in [examples/](examples/) - Read error messages carefully - Try simpler programs first ## Reporting Issues When reporting bugs: 1. Provide a minimal example 2. Show the error message 3. Include your Sesi version 4. Specify OS and Node.js version --- Happy programming with Sesi! 🚀 --- ## 8. README.md <p align="center"> <img src="./sesi-logo.svg" alt="Sesi Logo" width="250" /> </p> <h1 align="center">Sesi: A High-Performance Systems Language</h1> <p align="center"> <em>Pronounced "say-see" — What you say, you'll see.</em> </p> <p align="center"> <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript"> <img alt="Powered by Gemini" src="https://img.shields.io/badge/Powered%20By-Google%20Gemini-orange"> <img alt="Framework" src="https://img.shields.io/badge/Node.js-Engine-success?logo=node.js"> </p> <p align="center"> <strong>Sesi</strong> is a high-performance <strong>Systems Language</strong> designed for building resilient, stateful applications. It provides first-class primitives for process management, filesystem orchestration, and integrated reasoning, enabling developers to build complex logic with a fraction of the boilerplate required by traditional languages. </p> <p align="center"> <a href="https://code-with-sesi.netlify.app/">Homepage</a> </p> ## Installation You can install Sesi in three ways: ### 1. Global Installation via npm (Recommended) If you have Node.js installed, download Sesi directly from the npm registry: ```bash npm install -g sesi ``` ### 2. Standalone Executables Don't want to install Node.js? Download the standalone executables bundled for Windows, Mac, and Linux directly from our [Downloads page](https://code-with-sesi.netlify.app/downloads). Drop the executable in your system PATH and you're good to go! For macOS users, Sesi also supports a native PKG installer flow when building from source: ```bash npm run build:exe npm run build:mac:pkg ``` This generates installer packages in `releases/` (for available architectures) that install `sesi` to `/usr/local/bin`. ### 3. Build from Source (For contributors) ```bash git clone https://github.com/Misterscan/Sesi.git cd Sesi npm install npm run build npm install -g . # Unlock the `sesi` command locally ``` ## Quick Start You'll need a [Gemini API Key](https://aistudio.google.com/app/apikey) for the reasoning features. Create a `.env` file referencing your key where you run your scripts: ```env GEMINI_API_KEY="AIzaSy..." ``` Then run any program directly: ```bash # Standard script execution sesi main/start.sesi # Reasoning script example sesi examples/08_model_call.sesi # Run all examples sesi examples.sesi ``` # Local Execution (Development) If you choose not install `sesi` globally, use the helper npm scripts: ```bash npm run example 01_hello.sesi npm run example:ai 08_model_call.sesi npm run example:all ``` ## Language Overview Sesi is designed for developers who want to: - Write normal code (variables, functions, loops, etc.) - Call Reasoning directly within code using `prompt` and `model` blocks - Get structured outputs from Reasoning with type guarantees - Build Reasoning agents with memory and multi-step reasoning - Maintain full control and transparency ## Example ```sesi // Basic computation let x = 10 let y = 20 let result = x + y print result // 30 // Reasoning-powered code generation prompt generateCode {"Write a TypeScript function that reverses a string"} let code = model("gemini-3.1-pro-preview") {generateCode} print code ``` ## Documentation - [Getting Started](./QUICKSTART.md) - [Examples](./examples/) - [Language Specification](./docs/SPECIFICATION.md) - [Language Comparison Showcase](./docs/COMPARISON.md) - [Built-in Functions](./docs/BUILTINS.md) - [Reasoning Guide](./docs/SYSTEMS_REASONING.md) - [Distributed Systems](./docs/DISTRIBUTED_SYSTEMS.md) - [Runtime Architecture](./docs/ARCHITECTURE.md) ## AI Agent Context The root-level `SKILLS.md` file is a workspace context file for AI agents. It records repo-specific constraints such as valid Sesi syntax expectations, execution conventions, and the intended meaning of directories like `main/` and `main/tests/`. ## Project Structure ``` Sesi/ ├── SKILLS.md # AI-agent workspace context and repo guardrails ├── index.html # Sesi-generated landing page ├── eslint.config.mjs # ESLint configuration ├── dist/ # Compiled TypeScript output ├── example.js # Helper script to run basic examples ├── example-ai.js # Helper script to run Reasoning examples ├── package.json # Dependencies & scripts ├── tsconfig.json # TypeScript configuration ├── QUICKSTART.md # Quick start guide ├── IMPLEMENTATION_SUMMARY.md # Progress and tracking ├── src/ │ ├── types.ts # Type system & AST nodes │ ├── lexer.ts # Tokenization │ ├── parser.ts # AST generation │ ├── interpreter.ts # Execution engine │ ├── builtins.ts # Standard library │ ├── ai-runtime.ts # Gemini integration │ └── index.ts # Main entry point ├── bin/ │ └── sesi.js # CLI executable ├── examples/ # 18 sample programs demonstrating all features ├── main/ # Main entry and specialized tests │ ├── playground.sesi # Main playground script │ ├── start.sesi # Beginner script │ ├── build_website.sesi # Sesi-powered landing page generator │ └── tests/ # Debug and syntax scripts ├── tests/ # Test suite └── docs/ # Documentation (ARCHITECTURE, BUILTINS, SPECIFICATION, etc.) ``` ## Version 1.2 Features (In Progress) ### Core Language ✅ - **Variables & Bindings**: `let` for all bindings (const is deprecated). - **Functions**: Side-effect driven functions with typed parameters. - **Control Flow**: `if/else`, `while`, `for`, and `try/catch`. - **Collections**: Robust Arrays and Objects. - **Error Handling**: Structured `try/catch` for both runtime and Reasoning-level errors. - **Local Module Imports/Exports**: Import custom local `.sesi` modules cleanly using relative import/export syntax! - **Standard Library Modules**: Native support for imported standard libraries, including: - `std/math` (providing `PI`, `E`, `sqrt`, `pow`, `sin`, `cos`, etc.) - `std/time` (providing `sleep` and `now`) - `std/json` (providing JSON serialization/deserialization) ### Reasoning-Native Features ✅ - `prompt` blocks for message composition - `model()` calls with Reasoning provider configuration - `image()` calls with specific ratio/size generation capabilities - `structured_output()` for typed Reasoning responses - `tool_call()` for function calling - Basic memory for multi-turn reasoning - `read_file()`, `write_file()`, `to_json()`, `write_image()`, and `list_dir()` for local file I/O - **Native Concurrency**: `spawn()` and `exec()` for concurrent process management, and `multi_req(array<function>)` for physical parallel request execution. - **Logic Caching**: High-efficiency Sesi Logic Caching (`.sesi_cache.json`) for local call caching. - **Thinking Scale**: Scaled Gemini reasoning configurations using the `thinking` parameters. - **HTTP Client**: Built-in, native HTTP client support using `web_get(url)` and `web_send(url, body, headers)` with zero external dependencies. - **Async Polling**: Native looping to auto-resume generation when hitting `MAX_TOKENS` limit - **Utility Builtins**: `time()` and `random()` for robust coordination ### Type System - Static types: `number`, `string`, `bool`, `array<T>`, `object<T>` - Type inference - Union types for Reasoning response handling ## Roadmap ### V2: Advanced Reasoning - Long-term memory and context management - Custom tool definitions - Streaming responses ### V3: Agents & Orchestration - Agent definitions with state - Tool composition and chaining - Multi-agent collaboration - Persistent knowledge bases ## License MIT --- ## 9. ROADMAP.md # Sesi Systems Language Roadmap ## Version 1.0 - Foundation (Complete) **Status**: Complete V1.0 implementation **Ready for**: Exploration, learning, building prototypes **Not ready for**: Production systems (until v2.0 with error handling) **Next milestone**: V1.1 ### Core Language Features ✅ - [x] Variables and bindings (let) (const is deprecated) - [x] Functions with parameters and types - [x] Control flow (if/else, while, for, try/catch) - [x] Operators (arithmetic, logical, comparison) - [x] Arrays and objects - [x] Type system with inference - [x] Comments (// and /\* \*/) - [x] String concatenation - [x] Error handling (try/catch blocks) ### Integrated Reasoning Features ✅ - [x] Prompt blocks - [x] Reasoning model calls (model()) - [x] Structured output (structured_output()) - [x] Tool calling (tool_call()) - [x] Stateful context management (memory) ### Built-in Functions ✅ - [x] print, type, str, num, bool - [x] len, push, pop, join, split - [x] range, keys, values - [x] read_file, write_file - [x] spawn, exec (Concurrency & Systems) - [x] time, random (Utilities) - [x] Array and object operations ### Tooling ✅ - [x] Lexer and parser - [x] Tree-walking interpreter - [x] CLI executable (sesi) - [x] Examples (13 programs) - [x] Documentation ### Limitations - Interpreter is Single-threaded (use `spawn()` for concurrency) - No async/await - Blocking Reasoning calls - Limited error messages - No pattern matching - No generics or custom types --- ## Version 1.2 - Stability & Systems Logic (In Progress) **Status**: In Progress V1.2 implementation **Ready for**: Distributed systems orchestration and prototypes **Not ready for**: Massive-scale production (until v2.0 bytecode) **Next milestone**: V2.0 (Async & advanced reasoning) ### Improvements & Features ⌛ - [x] Systems Builtins: `spawn`, `exec`, `time`, `random` - [x] Concurrency: Async polling via file locks for completion and MAX_TOKENS - [x] Image Generation primitive (`image`) and Config blocks (`ratio`, `size`) - [x] File Management Builtins: `list_dir`, `write_image` - [x] Documentation improvements (Extensive Markdown guides) - [x] Bug fixes (tool_call argument passing resolved) - [x] Simple error recovery (Parser synchronization) - [x] Implicit statement termination for blocks ending in `}` - [x] Temporal Context Injection for reasoning calls - [x] Distributed Systems capabilities (Double-Check Write lock pattern) - [x] API reference (`BUILTINS.md`) - [x] Tutorial: Getting started (`QUICKSTART.md`) - [x] Cookbook: Common patterns (`SYSTEMS_REASONING.md`) ### Deferred to V2.0 ⏳ - [ ] Better error messages with line numbers and stack traces - [ ] REPL (Read-Eval-Print Loop) - [ ] String escape sequences & Multiline strings - [ ] Comments preservation (for docs) - [ ] Type hints in function signatures - [ ] Performance optimizations - [ ] Tutorial: Writing systems logic --- ## Version 2.0 - Advanced Concurrency & Logic (Q3-Q4 2026) **Focus**: Advanced reasoning features and native concurrency ### Async/Await Support - [ ] async/await syntax (language level) - [x] Parallel reasoning calls (native) - [ ] Promise-like operations - [x] Concurrent execution (Multi-process via `spawn`) ### Advanced Reasoning Features - [ ] Streaming responses - [x] Extended thinking/reasoning budget - [ ] Multi-step reasoning workflows - [ ] Tool composition and piping - [ ] Custom tool definitions - [ ] Function calling with automatic orchestration ### Memory System - [ ] Long-term memory with embeddings - [ ] Memory search by similarity - [ ] Context window management - [ ] Automatic summarization - [ ] Persistent storage (file-based) ### Error Handling - [ ] finally blocks (try/catch completed in V1) - [ ] Custom error types - [ ] Error recovery strategies - [ ] Retry logic with exponential backoff - [ ] Timeout handling ### Performance - [ ] Bytecode compilation - [x] Logic caching - [ ] Token counting and cost estimation - [ ] Lazy evaluation ### New Built-ins - [ ] String functions (upper, lower, trim, slice, etc.) - [ ] Array functions (map, filter, reduce, find, etc.) - [ ] Math functions (sqrt, sin, cos, floor, ceil, etc.) - [ ] Date/time functions - [ ] JSON parsing and serialization - [x] HTTP client (get, post) ### Module System - [x] import/export statements - [x] Standard library modules (std/math, std/time, etc.) - [ ] Third-party package management - [ ] Namespace support ### Tooling - [ ] Debugger with breakpoints - [ ] Profiler for performance analysis - [ ] AST visualization - [ ] Type checking tool - [x] Linter and formatter (ESLint integrated) ### Examples - [ ] Web scraper with reasoning analysis - [ ] Document processor (PDF, DOCX) - [ ] Chatbot with memory - [ ] Data pipeline with reasoning - [ ] API server (with async) --- ## Version 3.0 - Autonomous Systems Framework (2027) **Focus**: Full autonomous systems support ### Autonomous Framework - [ ] Framework definitions with state machines - [ ] Logic composition and chaining - [ ] Multi-process collaboration - [ ] Communication protocol - [ ] Persistence layer ### Knowledge Base - [ ] Vector database integration - [ ] Semantic search - [ ] Knowledge graph support - [ ] RAG (Retrieval-Augmented Generation) - [ ] Document indexing ### Advanced Patterns - [ ] Plan-and-execute workflows - [ ] Hierarchical task decomposition - [ ] Autonomous loop with safety checks - [ ] Reflection and self-improvement - [ ] Human-in-the-loop approval ### Ecosystem - [ ] Package registry - [ ] Community extensions - [ ] Plugin system - [ ] API server template - [ ] Dashboard/UI toolkit ### Examples - [ ] Autonomous research process - [ ] Customer support automation - [ ] Code generation and testing - [ ] Data analysis pipeline - [ ] Multi-process reasoning debate --- ## Version 4.0+ - Vision (2027+) **Focus**: Maturity, optimization, and specialization ### Potential Features - [ ] Compilation to JavaScript/WASM - [ ] JIT compilation for hot paths - [ ] Distributed execution - [ ] Cross-model orchestration (Gemini, Claude, etc.) - [ ] Vision model integration - [ ] Audio processing - [ ] Real-time streaming - [ ] Genetic programming / AutoML - [ ] Formal verification - [ ] Type refinement system ### New Language Constructs - [ ] Pattern matching - [ ] Generics and templates - [ ] Traits/interfaces - [ ] Macros - [ ] DSL support - [ ] Concurrent primitives (channels, mutexes) ### Performance - [ ] LLVM backend option - [ ] WebAssembly compilation - [ ] GPU acceleration - [ ] Distributed computing --- ## Feature Priority Matrix | Feature | Priority | V1 | V2 | V3 | V4+ | | --------------- | --------- | --- | --- | --- | --- | | Basic syntax | 🔴 High | ✅ | | | | | Functions | 🔴 High | ✅ | | | | | Reasoning calls | 🔴 High | ✅ | | | | | Error handling | 🔴 High | ✅ | ⏳ | | | | Async/await | 🔴 High | | ⏳ | | | | Streaming | 🟡 Medium | | ⏳ | | | | Systems Logic | 🟡 Medium | | | ⏳ | | | Knowledge base | 🟡 Medium | | | ⏳ | | | Module system | 🟡 Medium | | ⏳ | | | | Debugger | 🟢 Low | | ⏳ | | | | Compilation | 🟢 Low | | | | ⏳ | | GPU support | 🟢 Low | | | | ⏳ | --- ## Release Timeline ``` 2026 Q2 └─ v1.2 - Polish & stabilize 2026 Q3-Q4 └─ v2.0 - Advanced Reasoning & async 2027 Q1-Q2 └─ v3.0 - Autonomous Framework 2027 Q3+ └─ v4.0+ - Mature ecosystem ``` --- ## Community & Contribution ### Planned Community Activities - [ ] Public GitHub repository - [ ] Discord/Slack community - [ ] Monthly community calls - [ ] RFCs (Request for Comments) for major features - [ ] Contribution guidelines - [ ] Code of conduct ### How to Help (When Open Source) - [ ] Test programs and report bugs - [ ] Contribute documentation - [ ] Submit examples - [ ] Propose language features - [ ] Implement built-in functions - [ ] Build tools and extensions --- ## Backwards Compatibility ### Stability Guarantee - **v1.x → v1.y**: Full backwards compatibility - **v1.x → v2.0**: Mostly compatible, deprecation warnings for breaking changes - **v2.x → v3.0**: New features, old syntax still works ### Deprecation Policy 1. Announce deprecation (1 version ahead) 2. Show warnings in compiler 3. Provide migration guide 4. Remove in next major version --- ## Open Questions & Design Discussions ### For the Community 1. Should we support object-oriented programming (classes, inheritance)? 2. Should we add pattern matching or keep it simple? 3. Should memory be file-based by default or in-memory? 4. How should we handle multi-model orchestration? 5. Should processes be stateful or functional? ### Technical Decisions - Type system: Gradual or strict? - Concurrency: Async/await or coroutines? - Module system: Centralized registry or decentralized? - Error handling: Exceptions or Result types? --- ## Performance Goals | Metric | V1 | V2 | V3 | | ---------------------- | ---------- | ------ | ------ | | Startup time | <100ms | <100ms | <50ms | | Simple expression eval | <1µs | <100ns | <10ns | | Function call overhead | <10µs | <1µs | <100ns | | Reasoning call latency | 2-5s (API) | 2-5s | 2-5s | | Memory usage | <50MB | <50MB | <100MB | --- ## Inspiration & References ### Language Design - **Python**: Simplicity, readability - **Lua**: Lightweight, embeddable - **JavaScript**: Functions as first-class values - **Go**: Clear error handling - **Rust**: Type safety, memory safety ### Systems Reasoning - **LangChain**: Composable AI workflows - **AutoGPT**: Logic autonomy - **Semantic Kernel**: Model abstraction - **LLM frameworks**: Best practices ### Community - **Rust community**: Welcoming, inclusive - **Python community**: Documentation focus - **Go community**: Simplicity first --- ## Conclusion Sesi is designed to evolve with reasoning needs. The roadmap balances: - **Simplicity** (v1: core features only) - **Power** (v2: advanced reasoning patterns) - **Autonomy** (v3: autonomous framework) - **Scale** (v4+: production readiness) The journey from v1 (interpreter) to v4+ (distributed compiler) maintains backward compatibility while adding power where needed. **Current focus**: Ship v2.0 with native async/await and advanced reasoning patterns. --- ## See Also - [Specification](SPECIFICATION.md) - [Architecture](ARCHITECTURE.md) - [Built-ins](BUILTINS.md) - [Systems Reasoning](SYSTEMS_REASONING.md) - [Image Generation](IMAGE_GENERATION.md) - [Compare to other languages](COMPARISON.md) - [Examples](../examples) --- ## 10. sesi_ai_chronicles.md # The Sesi AI Chronicles: From Idea to Neural-Empathetic Execution --- ## 📖 Executive Summary The **Sesi AI Project** represents an extraordinary computational experiment: building a highly sophisticated, real-time, deep learning-powered conversational ecosystem natively within **Sesi**—a custom-designed, lightweight programming language with a tree-walking interpreter—and interfacing it seamlessly with modern **Python** console REPLs. From its initial concepts of simple keyword-matching bots, Sesi AI has evolved into a **hybrid neural-probabilistic engine** featuring: 1. **Offline Neural Networks:** Multi-class classification models trained from scratch natively in Sesi to map sentences to complex semantic domains. 2. **Cognitive Brain Morphing:** Conversational personas that dynamically shift their internal probability state machines (Markov chains) based on real-time neural inference of user statements. 3. **Dynamic Empathy Bridges:** Multi-layered, varied dynamic analogies bridging distinct technical domains to maximize conversational cohesion. 4. **Unbreakable Decoding Filters:** Modern LLM-grade decoding constraints (sliding lookback windows and strict Bigram-Blocking) that completely eradicate Markov graph-loop cycles. This chronicle serves as the definitive reference manual for the architecture, math, history, and codebase of Sesi AI. --- ## ⚙️ The Sesi Programming Language: Foundation & Architecture ### 1. Design Philosophy Sesi is structured as a retro-inspired, offline-first systems reasoning language. It was developed to eliminate external library bloat and operate with absolute procedural transparency. Sesi is executed via a **custom tree-walking interpreter**, parsing source code files with a `.sesi` extension into an Abstract Syntax Tree (AST) before executing node traversals. ### 2. Core Syntactical Features Sesi features a highly lightweight, C-like syntax: * **Dynamic Typings & Coercion:** Explicit converters allow seamless casting: `num("123")`, `str(45.6)`, `type(val)`. * **Dynamic Collections:** Array lists are fully supported with helper functions: `len(arr)`, `push(arr, element)`, `split(string, delimiter)`. * **Natively Built-In JSON Parsing:** Crucial for model synchronization and database ingestion: `from_json(raw_string)`, `to_json(object)`. * **Direct File System Access:** Natively handles persistent states: `read_file(path)`, `write_file(path, content)`. ### 3. Execution Characteristics and AST Constraints Because the tree-walking interpreter processes code instructions by traversing AST nodes directly on every statement: * **Computational Complexity (O-Notation):** String tokenization, Bag-of-Words mapping, and high-epoch training loops run entirely in single-threaded user space. * **Optimization Solutions:** Highly recursive operations are avoided, and large text operations are optimized using localized index boundaries rather than heavy string concatenations. --- ## 📈 The Sesi AI Evolution: Five Key Milestones ```mermaid graph TD A[Idea: Rule-Based Conversational Gateway] -->|Stage 1| B[Static Keyword Matchers] B -->|Stage 2: Probabilistic Walk| C[Markov Chain Bigram Walkers] C -->|Intermediary Testing| F[Baby Neural Network Testing Phase] F -->|Stage 3: Offline Deep Learning| D[Sesi Native Backpropagation Trainer] D -->|Stage 4: Cognitive Resonance| E[V4 Neural-Adaptive & Empathetic Chat REPL] ``` ### Stage 1: Static Rule-Based Conversational Gateways The system began as a traditional chatbot mapping exact keyword matches (e.g. `"synthesizer"`, `"gears"`) to static, pre-written response strings. If a message fell outside the defined vocabularies, it fell back to generic catch-all prompts. ### Stage 2: Probabilistic Bigram Markov Walkers To achieve natural linguistic variety, we mapped the 300 varied dialogue responses into localized word association tables (Bigram Tables). * The walker parsed a text corpus, mapping transitions: `transitions[word_1] = [word_2, word_3, ...]`. * To reply, the walker started at a matching keyword seed and walked the bigram associations, ending when a punctuation character (`.`, `!`, `?`) was generated. ### 🧪 Intermediary Phase: The Baby Neural Network & Proving Ground Testing Phase Before ever considering text keywords, Bag-of-Words vectors, or NLP semantic routing, we initiated a **Proving Ground Phase** to verify if a custom AST-traversing tree-walking compiler could execute multi-layer backpropagation math at all. We proved this natively using raw binary `1` and `0` inputs: #### 1. The Proving Ground: Zero-Dependency Pure Sesi XOR Classifier (`main/sesi_ai.sesi`) We engineered a 2-Layer Feedforward Neural Network trained **natively in pure Sesi** to solve the non-linear **XOR Logical Gate** table with absolute zero external language dependencies: * **The Math:** Structured a multi-layered network (2 Inputs, 2 Hidden Neurons, 1 Output Neuron) utilizing pure procedure-loop Sigmoid functions and derivatives: $$f(x) = \frac{1}{1 + e^{-x}}, \quad f'(y) = y \cdot (1 - y)$$ * **The Self-Healing Watchdog Engine:** Since random weight allocations can sometimes get stuck in local minima linear traps, we engineered an automated **Self-Healing Watchdog** directly inside the Sesi script: - All synaptic weights ($W_{hidden}$, $W_{output}$) and biases ($B_{hidden}$, $b_{output}$) were randomized to $[-2.0, 2.0]$. - The model underwent **4,000 backpropagation training epochs** at a learning rate ($\eta$) of `0.40`. - After the loop, the watchdog evaluated the final Mean Squared Error (MSE). - If $MSE \ge 0.01$, the watchdog triggered an automatic retry: ``` ⚠️ Stuck in linear saddle trap (MSE: 0.098). Re-seeding synapses... ⚡ Training attempt #2... ``` - It repeatedly re-seeded the synapses and re-ran the training until the model achieved perfect convergence ($MSE < 0.01$). * **Significance:** Once the watchdog printed `🎯 Perfect convergence achieved!`, Sesi saved the trained synapses to `sesi_model_weights.json` using `write_file(..., to_json(...))`. This proved mathematically that the custom Sesi tree-walker was capable of deep learning, greenlighting all future character routing systems! #### 2. The Native Sesi AND Logic Gate (`main/playground.sesi`) To test single-neuron floating-point calculations and weight adjustments on a simpler truth table, we trained a single-neuron classifier to solve the binary **AND Logical Gate**: * **The Math:** Developed a custom, high-speed **Fast Sigmoid (Softsign)** activation function to prevent custom AST float representation overflows: $$f(x) = 0.5 + 0.5 \cdot \left(\frac{x}{1 + |x|}\right)$$ accompanied by its exact analytical derivative $f'(y) = y \cdot (1 - y)$. * **Training Parameters:** Programmed weight and bias gradient backpropagation updates ($w_i \leftarrow w_i + \eta \cdot \text{error} \cdot f'(y) \cdot x_i$) over **1,500 epochs** at a learning rate ($\eta$) of `0.30`. * **Results:** Successfully converged to a near-zero Mean Squared Error (MSE) loss of **`0.003`**, saving calibrated parameters to `model_weights.json` and delivering 100% accurate binary logic evaluations. #### 3. The Telemetric Python XOR Network (`gpu_trainer.py`) To visualize training curves dynamically, we built a duplicate **2-Layer XOR Network** from scratch in Python, integrating direct graphics card telemetry: * **The Math:** Implemented standard Sigmoid functions. To guarantee symmetry breaking and force perfect deterministic convergence, weights were initialized dynamically to a wider $[-2.5, 2.5]$ range under seed `42` at a learning rate of `0.35` across `8000` epochs. * **GPU Hardware Telemetry:** Embedded an active loop querying your physical **NVIDIA GeForce GTX 1660 Ti** graphics card, tracking live dedicated VRAM consumption (GDDR6 pool), core graphics utilization, and core operating temperatures. * **Telemetry Dashboard:** Built a daemon local HTTP server on port 8000 to bypass browser CORS security protocols, streaming epoch-by-epoch predictions and training telemetry directly into the glowing SVG circular gauges of **[`training_hub.html`](file:///c:/Users/owner/Documents/Sesi/training_hub.html)**. ### Stage 3: Sesi Native Deep Learning & Zero-Shot Categorization Having successfully proved logical gate convergence, we scaled our architecture to NLP vector spaces. We built **`main/nn_personas_trainer.sesi`** and **`main/nn_responses_trainer.sesi`**. These scripts read raw character profiles and conversational sentences, constructed Bag-of-Words (BoW) feature vectors, and trained a 10x3 neural classifier from scratch over 1,500–2,500 epochs directly in the Sesi tree-walker, saving the weights to `response_classifier_weights.json`. ### Stage 4: V4 Natively Neural-Empathetic & Loop-Free Chat REPL The final stage brought absolute conversational symmetry: * **Netscape Navigator Web Portal:** Spawns two characters to debate, executing live neural inference on every turn to dynamically shift their brains. * **Terminal Chat REPL:** Interactive Python gateway featuring real-time HSL-colored confidence graphs, dynamic speech brain morphing, dynamic analogies, and loop-free decoding filters. --- ## 🧠 Neural Network Mathematics & Backpropagation Pipeline Sesi AI uses a **10x3 Single-Layer Feedforward Neural Network Classifier** to distribute semantic probability. ### 1. Vectorization Space (Bag-of-Words) The input text is tokenized, stripped of punctuation, and mapped against a **10-Feature Vocabulary**: $$\mathcal{V} = [\text{"synthesizer"}, \text{"vinyl"}, \text{"record"}, \text{"wood"}, \text{"gears"}, \text{"clock"}, \text{"compiler"}, \text{"framework"}, \text{"memory"}, \text{"offline"}]$$ Each string produces a 10-dimensional one-hot representation vector $\mathbf{x} \in \mathbb{R}^{10}$, where: $$x_i = \begin{cases} 1.0 & \text{if } \mathcal{V}_i \in \text{input\_tokens} \\ 0.0 & \text{otherwise} \end{cases}$$ ### 2. Forward Pass Mathematical Calculations The 3 output classes correspond directly to our conversational domains: $$\mathcal{C} = [\text{"audio"}, \text{"mechanical"}, \text{"systems"}]$$ For each class $c \in \{0, 1, 2\}$, the raw activation value $y_c$ is calculated against class biases $\mathbf{b} \in \mathbb{R}^3$ and weights $\mathbf{W} \in \mathbb{R}^{3 \times 10}$: $$y_c = b_c + \sum_{i=1}^{10} x_i \cdot W_{c, i}$$ To calculate normalized probability distributions $\mathbf{p} \in \mathbb{R}^3$ without overflow on limited custom interpreters, we implement a **Softmax activation function**: $$p_c = \frac{e^{y_c}}{\sum_{j=0}^{2} e^{y_j}}$$ ### 3. Backpropagation Gradient Updates Natively programmed in Sesi, the network is trained using **Mean Squared Error (MSE) loss** combined with Sigmoid/Softmax derivatives to adjust weights and biases over thousands of epochs: $$\mathbf{W}_{c, i} \leftarrow \mathbf{W}_{c, i} - \eta \cdot \frac{\partial \mathcal{L}}{\partial W_{c, i}}$$ Where $\eta$ represents the optimized learning rate (`0.30` - `0.45`). The final calibrated parameters are stored in **[`main/response_classifier_weights.json`](file:///c:/Users/owner/Documents/Sesi/main/response_classifier_weights.json)**: ```json { "weights": [ [18.51, 18.35, 20.76, -16.23, 0.08, -0.03, -15.94, -16.59, 0.42, -15.24], [-16.51, -16.25, -18.64, 17.02, -0.11, -0.27, -17.95, -18.82, 0.23, -17.17], [-16.76, -16.51, -18.92, -15.86, -0.35, -0.24, 18.66, 19.53, -0.40, 17.88] ], "biases": [-1.884, -0.418, -0.128] } ``` --- ## 🔗 The Win95 Netscape Navigator Dialectic Portal (V4) ### 1. Visual Aesthetics & Window Layout The Netscape Portal (**[`retro_chat.html`](file:///c:/Users/owner/Documents/Sesi/main/retro_chat.html)**) implements a beautiful, glassmorphic-inspired Win95 desktop layout: * A Win95 Teal desktop background (`#008080`). * A fully beveled Netscape Navigator program frame with Linear Gradient title bars, menu panels (`File`, `Edit`, `View`), beveled location input fields, and standard back/forward button controls. * A high-contrast, black-and-green IRC chat log console. * Real-time color-coded neural tag flags: `[NEURAL: audio]` in vibrant green, `[NEURAL: mechanical]` in bright yellow, and `[NEURAL: systems]` in deep cyan. ### 2. The Graph-Loop Repetition Vulnerability During early iterations of Markov dialogue walkers, characters would routinely fall into **infinite graph loops**. Because standard bigrams only evaluate a 1-word lookahead, the generator maintains no global semantic context. If the walker selects a common word pair (e.g. `"...how the..."`), the walk can jump back onto an identical path, repeating: > *"You should hear how the retro chiptune audio loop plays... You should hear how the retro chiptune..."* ### 3. Engineering the Unbreakable Decoding Filters To guarantee loop-free, natural prose, we designed and integrated modern LLM-grade decoding constraints natively into the walker: 1. **Extended Sliding Lookback (Size 15):** The walker maintains a history of the last 15 generated tokens. If a candidate word resides within this sliding window, it is instantly penalized and rejected. 2. **Strict Bigram Blocking (`No-Repeat-N-Gram` Size 2):** The walker tracks every transition pair `(w1 -> w2)` generated in the current sentence. If a proposed transition `current_word -> candidate` has **already occurred anywhere** in the history array, that candidate is completely banned and the walker selects an alternative. --- ## 📻 The Natively Neural-Empathetic Terminal Chat REPL (V4) The terminal chat portal (**[`main/terminal_chat.py`](file:///c:/Users/owner/Documents/Sesi/main/terminal_chat.py)**) provides an interactive, robust, and highly aesthetic command-line gateway. ### 1. Interactive Selection Directory On launch, the REPL prints a beautiful, double-beveled ASCII table listing all 20 specialized experts with their native age and categorized domains. The operator can input index `[0-19]` to dial in a secure offline connection to their desired persona. ### 2. HSL-Aligned Terminal Dials & Probability Bars Upon every conversational turn, the REPL prints a visually outstanding probability progress bar detailing the exact softmax confidence distribution: ```ansi [ NEURAL RESPONSE CLASSIFICATION ] [ AUDIO ████████████████ (100.0%) ] [ MECH ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ( 0.0%) ] [ SYSTEM ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ( 0.0%) ] [ ROUTING COGNITIVE FLOW -> AUDIO CLASS ] ``` ### 3. Cognitive Brain Morphing & Dynamic Empathy Bridges * **Dynamic Morphing:** If you are talking to a `systems` specialist but type an `audio` focused comment, the specialist **instantly morphs their transition matrices** to access the audio corpus, mirroring your cognitive focus. * **Empathetic Mismatch Bridges:** The specialist uses the mismatch to formulate a gorgeous technical analogy bridging their native specialty to your predicted domain (e.g. systems compiler pointers compared to mechanical gear leverages). * **Loop-Free Prefix Variation:** To prevent prefix monotony, we engineered a dynamic dictionary mapping relationship pairs to pools of **3-4 random prefix variations**, selecting a fresh one on every conversational turn! --- ## 📂 Mapping the Sesi AI Codebase The architecture is divided logically across modular scripts, databases, and UI assets: ### 1. Dynamic Code Files * **[`main/terminal_chat.py`](file:///c:/Users/owner/Documents/Sesi/main/terminal_chat.py) [NEW V4]:** The interactive python terminal REPL gateway. Integrates dynamic prefix variations, HSL colored probability bars, cognitive brain morphing, and loop-free bigram blocking. * **[`main/retro_chat_generator.sesi`](file:///c:/Users/owner/Documents/Sesi/main/retro_chat_generator.sesi) [NEW V4]:** Compiles the offline 3-category Markov brains, performs real-time neural inference loops in Sesi, runs the strict bigram-blocking walker, and writes the Win95 Netscape HTML portal. * **[`main/nn_personas_trainer.sesi`](file:///c:/Users/owner/Documents/Sesi/main/nn_personas_trainer.sesi) [NEW]:** Trains a multi-class neural network on conversational sentences to zero-shot classify all 20 character bios. * **[`main/nn_sentences_trainer.sesi`](file:///c:/Users/owner/Documents/Sesi/main/nn_sentences_trainer.sesi) [NEW]:** Inversely trains on character bios to zerozero-shot classify all 300 dialog sentences. ### 2. Calibrated Neural Synapses & Data Layers * **[`main/response_classifier_weights.json`](file:///c:/Users/owner/Documents/Sesi/main/response_classifier_weights.json):** The calibrated 10x3 weights and 3x1 biases file. * **[`main/personas.json`](file:///c:/Users/owner/Documents/Sesi/main/personas.json):** Roster of all 20 specialized expert character profiles. * **[`main/varied_responses.json`](file:///c:/Users/owner/Documents/Sesi/main/varied_responses.json):** The 300 varied conversational sentences corpus (100 audio, 100 mechanical, 100 systems). ### 3. Display Portals * **[`main/retro_chat.html`](file:///c:/Users/owner/Documents/Sesi/main/retro_chat.html):** The generated beveled Win95 Netscape Navigator portal loaded with loop-free, neural-adaptive dialectics. --- ## 🏆 Conclusion & The Future of Sesi AI Sesi AI proves that complex, cognitively adaptive AI environments do not require massive modern cloud API integrations or bloated dependency frameworks. By layering **simple feed-forward neural networks** over **probabilistic Markov structures** and applying **strict LLM-grade decoding constraints (bigram blocking)**, Sesi AI produces highly articulate, technically dense, and contextually empathetic dialog natively on localized hardware. The Sesi compiler and its neural pipelines stand ready for further telemetry, higher-dimensional bag-of-words vocabularies, and expanded multi-layered neural configurations. --- ## 11. SYSTEMS_REASONING.md # Systems Reasoning & Logic Guide ## Overview Sesi is a **Systems Language** that treats reasoning as a first-class execution primitive. In this paradigm, AI is used to evaluate state, make logical decisions, and handle complex patterns within a systems-level architecture. This guide covers how to leverage Sesi's systems-level constructs (`spawn`, `exec`, `try/catch`) alongside its reasoning primitives (`model`, `prompt`, `structured_output`) to build resilient, stateful applications. ## 1. Concurrency & Systems Coordination The core of Sesi's power lies in its ability to manage distributed execution. Using the `spawn()` builtin, you can launch multiple concurrent Sesi processes that coordinate via shared state or the filesystem. A master script can launch concurrent processes and poll for their completion. ```sesi spawn("atm_deposit.sesi") spawn("atm_withdraw.sesi") let finished = false while !finished { try { if read_file("bank/done_count.txt") == "2" { finished = true } } catch (e) { // Wait on I/O contention let i = 0 while i < 1000 { i = i + 1 } } } print "Swarm task completed." ``` ### Coordination & Distributed Locking When multiple processes access shared resources, use Sesi's `try/catch`, `time()`, and `random()` builtins to implement mutual exclusion (locking) via the **Double-Check Write** pattern. ```sesi let id = "With_" + str(time()) + "_" + str(random()) let locked = true while locked { let status = "error" try { status = read_file("bank/lock.txt") } catch (e) { status = "error" } if status == "unlocked" { try { write_file("bank/lock.txt", id) let i = 0 while i < 500 { i = i + 1 } if read_file("bank/lock.txt") == id { locked = false } } catch (e) { status = "error" } } else { let j = 0 while j < 1000 { j = j + 1 } } } ``` --- ## 2. AI as a Reasoning Primitive In an orchestrated system, AI is used to make decisions that would be too complex for static logic. Prompts are **composable message templates** that evaluate to strings. ### Basic Prompt ```sesi prompt simplePrompt {"Hello, Sesi!"} print simplePrompt // "Hello, Sesi!" ``` ### Prompts with Variables ```sesi let name = "Alice" prompt greeting {"Hello, " name "! How are you?"} print greeting // "Hello, Alice! How are you?" ``` ### Composing Prompts ```sesi prompt part1 {"First part"} prompt part2 {part1 " Second part"} print part2 // "First part Second part" ``` ### Prompts in Functions ```sesi let text = "Testing" let language = "Spanish" fn translatePrompt(text: string, language: string) -> string {prompt translate {"Translate " text " to " language ": "} return translate} print translatePrompt(text, language) ``` ## 2. Model Calls Call Gemini with a prompt and get back text. ### Basic Model Call ```sesi let response = model("gemini-3-flash-preview") {"What is machine learning?"} print response ``` ### Model Configuration ```sesi let creative = model("gemini-3.5-flash") {thinkingLevel: "low"} {"Write a creative poem about technology."} print creative // Config options: // - thinkingLevel: "minimal", "low", "medium", "high" (natively configures Gemini's reasoning budget) // - max_tokens: max length of response (OPTIONAL: if not specified, will use the model's default max tokens=2048) // - temperature / top_k / top_p: *Will be deprecated in Gemini 3.x+, use thinkingLevel instead (reasoning is mathematically optimized for default settings)* ``` ### Model Selection ```sesi // Fast model for simple tasks let text = " Coding with Reasoning systems language is fun!" let quick = model("gemini-3.1-flash-lite") {"Summarize this in one sentence:" text} // Powerful model for complex reasoning let code = "def calculate_sum(n): total = 0 for i in range(1, n): total += i return total" let smart = model("gemini-3.1-pro-preview") {"Analyze this code for bugs:" code} // Efficient model for many calls let item = " Programming Languages" let cheap = model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify:" item} print quick print smart print cheap ``` ### Available Models (v1.2) - `gemini-2.5-flash` - Legacy, but supported. 1M tokens. - `gemini-2.5-pro` - Legacy, but supported. 1M tokens. - `gemini-2.5-flash-image` - Standard image model. (No `512` image size support for this model. Only `1K` is supported.) - `gemini-3-flash-preview` - Fast, balanced, legacy preview. - `gemini-3.1-flash-lite` - Fastest, most cost-efficient. - `gemini-3.5-flash` - Standard GA Model. Fast, balanced, supports all native thinking effort levels (`minimal`, `low`, `medium`, `high`). - `gemini-3.1-pro-preview` - Most powerful reasoning model, doesn't support `minimal` thinking (falls back to `low`). - `gemini-3.1-flash-image-preview` - Cost efficient image generation model. - `gemini-3-pro-image-preview` - High quality image generation model. (No `512` image size support for this model.) #### Planned for (v2+) - `OpenAI` integration (GPT, Dall-E, etc.) - `HuggingFace` integration - `Midjourney` integration - `Newer Reasoning Models` - Native upgrades ### Passing Images as Input Pass one or more local image files to `model()` or `image()` via the `images` config key. The runtime reads each file, base64-encodes it, and injects it as a vision part before the prompt text. ```sesi // Single image let referenceImage = "stills/frame_03.jpg" let caption = model("gemini-3-flash-preview") {images: referenceImage} {"What is the subject of this photograph?"} print caption // Multiple images let pair = ["ref_a.png", "ref_b.png"] let diff = model("gemini-3-flash-preview") {images: pair} {"List every visual difference between these two."} print diff // Mixed with other config keys let scannedDocument = "doc_scan.jpg" let result = model("gemini-3.5-flash") {images: scannedDocument, thinkingLevel: "low", max_tokens: 2048} {"Transcribe all text visible in this scan."} write_file("transcript.txt", result) ``` See [Image Generation & Input](IMAGE_GENERATION.md) for the full reference. ## 3. Structured Output Get typed responses from Reasoning with field validation. ### Basic Structured Output ```sesi let analysis = structured_output({sentiment: string, confidence: number, summary: string}) (model("gemini-3-flash-preview") {"Analyze sentiment of: " text "Return JSON with sentiment, confidence (0-1), and summary"}) print analysis["sentiment"] // "positive" print analysis["confidence"] // 0.85 print analysis["summary"] // "..." ``` ### Schema Definition ```sesi // Schema is a record with field types let schema = {title: string, author: string, pageCount: number, tags: string, isFiction: bool} let bookInfo = structured_output(schema)(model("gemini-3-flash-preview") {"Extract book metadata as JSON from: " description}) print bookInfo["title"] ``` ### Parsing Tips - Always include instructions for JSON format - Specify the exact schema in the prompt - Use "thinkingLevel": "low" for fast, consistent parsing - Validate output structure in code ```sesi let listText = "eggs, milk, bread, cheese, fruit, vegetables" let output = structured_output({items: string})(model("gemini-3.5-flash") {thinkingLevel: "minimal"}{"Return JSON with items array containing: " listText}) // Validate if type(output["items"]) == "array" {print "Got" str(len(output["items"])) "items"} // Got 6 items ``` ## 4. Tool Calls (Function Calling) Let Reasoning call functions in your program. ### Define Callable Functions ```sesi let city = "New York" fn getWeather(city: string) -> string {let weather = model("gemini-3.1-flash-lite"){"What is the weather like in " city} return weather} let result = getWeather(city) print result // When defined inside a function, local variables MUST be defined on new lines. // (A current limitation of the parser). fn calculateTax(amount: number, rate: number) -> number {let amount = 100 let rate = 0.08 return amount * rate} let result = calculateTax() print result ``` ### Reasoning Makes Tool Calls ```sesi let tax = tool_call(calculateTax)(model("gemini-3.1-flash-lite") {"Calculate 8% sales tax on $100"}) print tax // 8.0 ``` ### Multiple Tool Availability (Future) ```sesi // v2: Allow Reasoning to choose from multiple tools let result = with_tools([getWeather, calculateTax, getTime]) {model("gemini-3-flash-preview") {"What's the weather in NY and the sales tax on $50?"}} ``` ## 5. Memory & Conversation Maintain context across multiple Reasoning calls. ### Simple Memory ```sesi memory chat {"You are a helpful assistant. Be concise."} // First turn let response1 = model("gemini-3-flash-preview") {chat "User: Hello!"} // Update memory with conversation chat = chat + "Assistant: " + response1 // Second turn let response2 = model("gemini-3.1-flash-lite") {chat "User: How are you?"} print response2 // Has context from turn 1 ``` ### Memory in Functions ```sesi memory conversation {"Chat history: "} fn chat(userMessage: string) -> string {let fullPrompt = conversation + "User:" + userMessage let response = model("gemini-3-flash-preview") {fullPrompt} // Append to memory conversation = conversation + "User:" + userMessage + "Assistant:" + response return response} let msg = "What is the capital of France? " print "User:" msg print "Assistant:" chat(msg) print "Updated Memory!" ``` ### Memory Best Practices - Keep memory concise to save tokens - Summarize old messages periodically - Reset memory when topic changes - Monitor token usage ```sesi // Summarize old memory memory conversation {"User: Hello! Assistant: Hi there! User: How are you? Assistant: I'm great!"} fn summarizeMemory() {let oldConversation = conversation let summary = model("gemini-3.1-flash-lite") {"Summarize this conversation concisely:" oldConversation} conversation = "Previous summary:" + summary + "Recent messages: " + oldConversation} print "Original Memory:" conversation summarizeMemory() print "Summarized!" print conversation ``` ## 6. Practical Patterns ### Classification ```sesi let categories = "fruit, vegetable, grain" let item = "banana" fn classify(item: string, categories: string) -> string {return model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify this item into one category. Categories: " categories " Item: " item " Return only the category name."}} print "Item: " item //banana print "Category: " classify(item, categories) //fruit ``` ### Extraction ```sesi let text = "Elon Musk is the CEO of Tesla and SpaceX." fn extractEntities(text: string) -> object {let result = structured_output({people: string, places: string, organizations: string}) (model("gemini-3.5-flash") {thinkingLevel: "minimal"}{"Extract named entities from:" text}) print "Name(s) found: result" return result} print extractEntities(text) ``` ### Translation ```sesi let text = "Hello, world!" let language = "Spanish" fn translate(text: string, language: string) -> string {return model("gemini-3-flash-preview") {"Translate to" language ":" text}} print "Translation:" print translate(text, language) ``` ### Image Generation Like `model`, the `image` command evaluates prompts and accepts configuration variables mapping accurately to backend SDKs requirements. ```sesi let logo = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "512"} {"A high quality vector logo representing a new programming language named Sesi"} write_image("logo.png", logo) print "Image generated!" ``` ### Code Generation ```sesi let requirement = "Write a function that reverses a string." fn generateCode(requirement: string) -> string {return model("gemini-3.5-flash") {thinkingLevel: "low"} {"Generate JavaScript code for:" requirement "Only provide code, no explanation."}} print "Code generation:" print generateCode(requirement) ``` ### Analysis ```sesi let text = "I love Sesi!" fn analyzeSentiment(text: string) -> object {return structured_output({sentiment: string, score: number, explanation: string}) (model("gemini-3-flash-preview") {"Analyze sentiment of:" text})} print "Sentiment analysis:" print analyzeSentiment(text) ``` ## 7. Error Handling Reasoning operations can fail. Handle gracefully. ### Try/Catch (v1.2) ```sesi try {let response = model("gemini-3-flash-preview") {"Analyze" text} print response} catch (e) {print "Reasoning call failed" print e} ``` ### Current Failure Behavior - `model()` throws when the Gemini SDK fails or when no text is returned. `MAX_TOKENS` finish reasons are handled natively via a polling loop to automatically complete long outputs. - `structured_output()` first tries to parse JSON from the model text, then retries with a coercion prompt. - If structured parsing still fails, the runtime currently logs the error and returns `{}`. ### Validation After Success ```sesi let text = "Coding is evolving rapidly!" fn safeAnalyze(text: string) { try {let result = structured_output({sentiment: string, score: number})(model("gemini-3.1-flash-lite") {"Analyze sentiment and return JSON for:" text}) if len(keys(result)) == 0 {print "Structured parsing failed" return null} return result} catch (e) {print e return null}} print "Analysis Result: " safeAnalyze(text) ``` ## 8. Performance Tips ### Minimize API Calls ```sesi // Bad: Calls API 3 times for item in items {let analysis = model("gemini-3.1-flash-lite") {"Analyze:" item}} print analysis // Better: Batch into one call (v2: parallel calls) let analyses = model("gemini-3.1-flash-lite") {"Analyze each:" join(items, " ")} print analyses ``` ### Use Cheaper Models for Simple Tasks ```sesi // Simple classification → flash-lite let category = model("gemini-3.1-flash-lite") {"Classify:" item} print category // Complex reasoning → pro let analysis = model("gemini-3.1-pro-preview") {"Deep analysis of:" complex_problem} print analysis ``` ### Reduce Token Usage ```sesi // Long prompts waste tokens // Bad: let response = model("gemini-3-flash-preview") {"Here is a very long system prompt that repeats itself... " "Please analyze the following text very carefully..." text} print response // Better: let response = model("gemini-3-flash-lite") {"Analyze:" text} print response ``` ### Cache Repeated Prompts ```sesi // Bad: Same analysis done multiple times for person in people {let assessment = model("gemini-3.1-flash-lite") {"Assess based on criteria A, B, C: " person}} print assessment // Better: Reuse cached prompt let people = ["Elon Musk", "Bill Gates", "Steve Jobs"] fn assessPerson(person: string) -> string {return model("gemini-3.1-flash-lite") {"Assess on A, B, C: " person}} for person in people {print assessPerson(person)} ``` ## 9. Token Counting (Future) V2 will include token counters: ```sesi // Planned for v2: let tokens = count_tokens(text, model) print "This costs " str(tokens * PRICE_PER_TOKEN) " cents" // Plan memory size let remaining = MAX_TOKENS - count_tokens(memory, model) if remaining < 500 {summarizeMemory()} print "Memory size: " count_tokens(memory, model) ``` ## 10. Advanced: Custom Reasoning Workflows ### Multi-Stage Reasoning Workflow ```sesi let text = "Climate change is a long-term shift in global or regional climate patterns. Often climate change refers specifically to anthropogenic climate change, which is caused by human activities, primarily fossil fuel burning, which increases heat-trapping greenhouse gas levels in Earth's atmosphere. The term is frequently used interchangeably with the term global warming, though the latter refers specifically to the long-term heating of Earth's climate system observed since the pre-industrial period due to human activities." fn smartSummarize(text: string) -> string // Chain multiple Reasoning operations // Step 1: Extract key points {let keyPoints = model("gemini-3.1-pro-preview") {thinkingLevel: "low"} {"Extract 5 key points from:" text} // Step 2: Analyze topics let topics = structured_output({ topics: string })(model("gemini-3.5-flash") {thinkingLevel: "low"} {"Identify topics in:" keyPoints}) // Step 3: Generate summary let summary = model("gemini-3-flash-preview") {"Summarize with topics " topics ":" keyPoints} return summary} print "Summary:" smartSummarize(text) ``` ### Reasoning Pattern ```sesi let analysis = model("gemini-3.5-flash") {thinkingLevel: "medium", max_tokens: 8192} {"Reason carefully about:" problem} print analysis ``` ### Few-Shot Prompting ```sesi let text = "banana" fn classifyWithExamples(text: string) -> string {return model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify as A, B, or C" "Examples:" "'apple' -> A" "'dog' -> B" "'happy' -> C" "Classify: " text}} print "Classification:" classifyWithExamples(text) ``` --- ## See Also - [Compare to other languages](COMPARISON.md) - [Language Specification](SPECIFICATION.md) - [Image Generation](IMAGE_GENERATION.md) - [Architecture](ARCHITECTURE.md) - [Built-ins](BUILTINS.md) - [Examples](../examples/) - [Roadmap](ROADMAP.md)