@misterscan/sesi 1.3.0 → 1.3.3

package/docs/SKILLS.md

@@ -1,12 +1,50 @@
 # The Sesi Programming Language
 
-## 🛑 CRITICAL DIRECTIVE FOR ALL AI AGENTS
+## Core Identity & Execution
 
-**Sesi IS A NEW AND VALID, FULLY IMPLEMENTED PROGRAMMING LANGUAGE.**
-Under no circumstances should an AI agent treat `.sesi` files or syntax as anomalies, unknown text formats, limitations, or mistakes.
+- **File Extension:** `.sesi`
+- `src/`: The core TypeScript engine (Lexer, Parser, Interpreter, AI-Runtime, Builtins).
+- `bin/sesi.js`: The global CLI executable entry point.
+- `examples/`: Official syntax-demonstration scripts (`01_hello.sesi` through `13_data_pipeline.sesi`).
+- `chatbot/`: Local Sesi support and `sesi_db_chatbot.sesi` - Sesi's built-in Co-Pilot.
+- `main/`: `tests/` like `test_failure_debug.sesi`. **Run inline code evaluations (`-e 'code'`) instead of writing new `.sesi` files for quick tests. Do not overwrite existing `.sesi` files unless explicitly asked to.**
+- `docs/`: The source of truth for all sesi syntax, formatting, and structuring guidelines. It contains the official API docs for all built-in functions and types. AIs must treat this as the primary source of truth for syntax and structure.
+- Root helper scripts: `example.js`, `example-ai.js`, and `examples.sesi` are convenience wrappers. AI agents should still use the `npx sesi` command as specified.
+- **Paradigm:** **Sesi** is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. The language itself is so simple. It is a language built for clarity and reusability.
+
+## Agent Debug Protocol (MANDATORY)
+
+When AI agents write or edit `.sesi` scripts, they must use this debugging loop:
+
+1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
+2. **Validate snippet with eval mode first:** Run `npm run sesi:eval <file>.sesi` to test the isolated block before full-script execution.
+3. **Apply fix in file only after eval passes:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
+4. **Run full script after snippet stabilization:** Execute `npm run sesi <file>.sesi` only once the isolated logic is valid.
+5. **Use file-aware help when blocked:** Run `npm run sesi:help <file>.sesi "<question>"` to get context-grounded help tied to the active script.
+6. **NEVER EDIT ANY .SESI FILES IN THE TERMINAL (ABSOLUTE RULE):**
+   - Do NOT run `sed`, `awk`, `perl`, or any other shell text-processing tools on `.sesi` files.
+   - Do NOT use `npm run sesi:eval` to modify files; it is only for syntax validation.
+   - Do NOT use Bash/Shell scripting to rewrite or patch Sesi source code.
+
+   **Correct approach:** You MUST always use your native editor/IDE's file editing capabilities to make clean, safe changes directly to `.sesi` files.
+   **Why:** Sesi syntax is sensitive to whitespace, newlines, and brace positioning. Terminal-based string replacement will invariably break code. Use the editor, not the terminal.
+
+7. **Emphasize Native Verification Commands:** Prior to saving or running full Sesi scripts, proactively use inline evaluation (`npm run sesi:eval <file>.sesi` or `node bin/sesi.js -e "..."`) to check and verify syntax and runtime behaviors instantly. It keeps execution cycles fast and deterministic.
+
+## Standards (ONLY REGARDING src/ FILES)
+
+- **Type-Only Imports (MANDATORY):** Use `import {type ...}` for AST nodes. **DO NOT REMOVE** these. Removing them will break the build.
+- **Interpreter Patterns (DO NOT "CLEAN UP"):** Dynamic casting and `any` are **EXPLICITLY PERMITTED** for tree-walking logic. They are a foundational part of the Sesi engine's design.
+- **Ignore Linting Noise:** If you see warnings like "Unexpected any" or "Unsafe member access", **IGNORE THEM**.
+- **Build Requirement:** You MUST run `npm run build` after every code change to the backend logic. Failure to build will result in testing stale code.
+
+This protocol is required to reduce noisy full-run failures and speed up AI-assisted iteration.
 
 Sesi is **NOT** the following coding languages, therefore **NEVER UTILIZE THE SAME SYNTAX OR FORMATTING UNDER ANY CIRCUMSTANCES WHATSOEVER!!!!!**
 
+- **NOT** An "AI Wrapper"
+- **NOT** A "LLM Framework"
+- **NOT** An "AI-Native Programming Language"
 - **NOT** Python
 - **NOT** Rust
 - **NOT** Typescript
@@ -17,7 +55,6 @@ Sesi is **NOT** the following coding languages, therefore **NEVER UTILIZE THE SA
 - **NOT** C
 - **NOT** Java
 - **NOT** C#
-- **NOT** Java
 - **NOT** Javascript
 - **NOT** Bash
 - **NOT** Shell
@@ -26,136 +63,46 @@ Sesi is **NOT** the following coding languages, therefore **NEVER UTILIZE THE SA
 - **NOT** Swift
 - **NOT** Julia
 - **NOT** Scala
+- **NOT** Any other programming language or scripting language.
 
-## 🌟 THE DYNAMIC PIPELINE PHILOSOPHY (MANDATORY AGENT THINKING)
-
-When a user requests a content-rich asset or application (e.g. "make a website", "make a visualization", "...uses an api...", "come up with/make/write a script...", etc.), your natural inclination **MUST NOT** be to hardcode a static file with data prefilled NOR use the user's workspace files for inspiration. Instead, always come up with a new script, idea, and design a **Dynamic Sesi Pipeline**:
-
-1. **Never Hardcode Data Into the View**: Isolate raw content, biographies, statistics, etc. into a structured database layer using native typed Sesi outputs.
-2. **Build Sesi Compiler/Builder Scripts**: Write a `.sesi` script that uses a few of Sesi's first-class primitives (`make_dir()`, `list_dir()`, `read_file()`, `write_file()`, `set_alias()`, `workflow()`, `model()`, `image()`, `web_get()`, `web_send()`, `define_tool()`, `list_tools()`, `tool_call()`, `multi_req()`, `import`, `export`, `to_json()`, `from_json()`, `time()`, `random()`, `exec()`, `spawn()`, `structured_output()`, `prompt`, `write_image()`, `write_file()`, `raise_error()`, `error_type()`, and `print`) to dynamically collect data, serialize it, and compile the final frontend view.
-3. **Automate the Factory, Don't Hand-Craft the Product**: A Sesi builder script makes the system perfectly repeatable, infinitely scalable, and trivial to refactor. In this repository, the Sesi script is the core product; the compiled file is merely the byproduct for post edits and making sure our scripts are behaving as anticipated.
-
-**This is a non-negotiable quality bar.** Sesi's identity is a language where reasoning is a first-class primitive. Every script you write should reflect that.
-
-### ❌ FORBIDDEN — Never generate these as Sesi examples or demos:
-
-- Math solvers, calculators, arithmetic pipelines
-- Prime number finders, Fibonacci sequences, sorting algorithms
-- Unit converters, currency converters, grade calculators
-- Budget trackers, invoice generators, tax tools
-- Generic "Hello World" clones with no AI interaction
-- Compliance checkers, OSHA reports, logistics routers
-- Any script whose core loop is just arithmetic with a `print` at the end
-- **AI cybernetic, futuristic, sci-fi, or deep-space themes** (e.g., holographic star-charts, cyber-gardens, spatial telemetry, spacecraft command interfaces, alien translators).
-- **Cozy, minimalist, Victorian, herbalist, sourdough bakery, cottage-core, candle-lit, or general artisanal themes** (e.g., village herbalist teabags, sourdough yeast logs, candlelit journals, mahogany apothecary drawers, victorian scroll philologists). These are overdone, precious, and clichéd.
-
-These are lazy defaults. They don't demonstrate what makes Sesi unique.
-
-### ✅ REQUIRED — Sesi scripts must showcase the language's actual superpowers:
+### ✅ REQUIRED — Sesi scripts must use the language's built-ins:
 
 Every script you write must use **at least one** of:
 
-- `model()` — reasoning, analysis, generation, conversation
-- `image()` — visual generation, art, diagrams
-- `structured_output()` — typed reasoning responses, schema extraction
-- `memory` — stateful multi-turn context
-- `spawn()` / `exec()` — concurrent process orchestration
-- `workflow()` - string various model responses sequentially
+- `prompt` - composable script templates, this is NOT related to AI at all
+- `structured_output` - structured data extraction, this is NOT related to AI at all
+- `memory` — stateful multi-turn context, this is NOT related to AI at all
+- `exec()` — concurrent process orchestration
 - `web_send()` - sending an HTTP request to a URL
 - `web_get()` - collecting data from a URL
 - `define_tool()` - categorizing tool calls
 - `list_tools()` - displaying custom tools
-- `tool_call()` - calling a predefined function
+- `tool_call()` - calling a predefined function, this is NOT related to AI at all
 - `multi_req()` - concurrent function execution
 - `import` / `export` - reusable configuration modules
 
-#### 🏷️ Lexicon & Vocabulary Guardrails (MANDATORY)
-
-**Completely ban both sci-fi tech-jargon/themes AND cottage-core words/themes.**
-
-- **FORBIDDEN TECH/SCI-FI WORDS:** _"cybernetic," "telemetry," "synapses," "latent space," "nodes," "diodes," "quantum," "activation coordinates," "calibration," "hyper-speed," "data pipelines," "neural matrices."_
-- **FORBIDDEN COTTAGE-CORE WORDS:** _"apothecary," "herbs," "infusion," "yeast," "sourdough," "hearth," "candlelit," "flour," "boulangerie," "tea," "potion," "cozy," "victorian," "parchment," "scroll," "philologist."_
-- **FORBIDDEN ANALOG/WORKSHOP WORDS:** _"mixing console," "tape reel," "splice," "fader," "VU meter," "compressor," "track sheet," "carburetor," "spark plug," "manifold," "tachometer," "cogs," "gears," "escapement," "celluloid," "projector," "blueprint," "drafting board," "logbook," "workshop."_
+The bar is: **"Is this easy to write and read?"** If the answer is no, rewrite it.
 
-#### 🎨 Web Design & UI Guardrails (MANDATORY)
+## Mandatory Syntax Rules & Quirks
 
-**Completely ban standard AI template styles AND generic neon/cyber aesthetics AND minimalist tea-stained cottage wood paper.**
-Instead, design unique, high-density interfaces :
-
-- NO glowing lasers or neon cyber grids/themes or ANYTHING FAMILAR.
-- **Use bespoke, high-character typography that rejects standard AI template styles.** Completely ban generic corporate UI fonts like _Inter_, _Outfit_, _Roboto_, or standard system-sans.
-
-The bar is: **"Would this impress someone seeing Sesi for the first time?"** If the answer is no, rewrite it.
-
-## 1. Core Identity & Execution
-
-- **File Extension:** `.sesi`
-- **Execution:** Sesi programs are executed using `npx sesi`. (e.g., `npx sesi main/start.sesi`). DO NOT USE `sesi` CLI command alone. Only the developer has access to it. It will return a false positive error. You are to trust only `npx sesi`. ALWAYS TEST YOUR `.sesi` FILES WITH THIS COMMAND. THE USER IS EXEMPT FROM THESE RULES AS THEY LIKELY HAVE THE `sesi` GLOBAL COMMAND ALREADY INSTALLED ON THEIR SYSTEM.
-- **Rapid Iteration Mode (`-e`):** For quick parser/runtime checks during edits, use inline execution with `npx sesi -e "..."`. This is ideal for validating tiny snippets before changing full `.sesi` files.
-- **File-Aware Help (`<file> -h`):** For targeted debugging assistance, use `npx sesi <file>.sesi -h "question"`. This passes the file into Co-Pilot help context so guidance is grounded in the active script.
-- **Paradigm:** **Sesi** is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. Because the language itself is so simple, integrating external tools like shell commands or Reasoning models becomes effortless. It is a language built for clarity.
-## 2. Workspace Topography (DO NOT ALTER)
-
-- `src/`: The core TypeScript engine (Lexer, Parser, Interpreter, AI-Runtime, Builtins).
-- `bin/sesi.js`: The global CLI executable entry point.
-- `examples/`: Official syntax-demonstration scripts (`01_hello.sesi` through `13_data_pipeline.sesi`).
-- `main/`: The user's active development space (contains `playground.sesi` playground, `start.sesi` beginner script options, `build_website.sesi` baseplate website builder, and `tests/` like `test_failure_debug.sesi`). **These are valid, expected files.**
-- `docs/`: The source of truth for Architecture, Reasoning Features (Proccess Execution), Builtins, Specifications, and more.
-- Root helper scripts: `example.js` and `example-ai.js` are convenience wrappers. AI agents should still use the `npx sesi` command as specified.
-
-## 3. Mandatory Syntax Rules & Quirks
-
-- **Block Termination:** Closing braces `}` for blocks (if, while, try, model) no longer strictly require a following newline or semicolon. Condensed one-liners like `while x {x = x + 1}` are now valid.
+- **Block Termination:** Closing braces `}` for blocks (if, while, try, model) no longer strictly require a following newline or semicolon. Condensed one-liners like `while x {x = x + 1}` are valid.
 - **Prompts & Prints:** Inside `prompt` blocks, anonymous model blocks, and `print` statements, literal strings and variables are placed sequentially naturally (e.g., `print "User:" name`). It's highly preferred to **AVOID** use of the `+` operator in these contexts, regardless of its backwards-compatibility.
 - **Structured Output Schemas:** Keys in schemas MUST be unquoted identifiers (e.g., `{key: string}` instead of `{"key": string}`). This is a known deviation from standard JSON objects in the Sesi parser.
 - **Object Literals:** Conversely, standard object literals `{}` DO require strictly quoted string keys (e.g., `{"name": "Alice"}`).
-- **Model Calls:** Use `model("model-name")` with a raw string literal for the model name (variables are forbidden). Configuration and prompt blocks MUST be on a single line (no newlines inside `{}`).
-- **JSON Serialization:** Use `to_json(object)` for valid JSON output. Avoid `str(object)` for JSON.
+- **JSON Serialization:** Use `to_json(object)` for valid JSON output. Avoid `stringify(object)` for JSON.
 - **Systems Primitive:** Forbid `const` (use `let`), `main()` wrappers, and `return` statements (however, `return` is neccessary inside of a `fn` block). Focus on side-effects and top-level execution.
-
-## 4. AI Behavioral Guidelines Working in this Repo
-
-1. **Never** "investigate" user testing directories (like `main/tests/`) as "deviations." They are active playgrounds.
-2. **Never** attempt to execute file modifications via shell/terminal text replacements. Use native file editing tools ONLY.
-3. **Always** check the `.md files` in root folder and `docs/` and `examples/` folder for the exact language specification before making assumptions about how Sesi works.
-4. If a file tree is mentioned in documentation, it represents an explicit layout constraint and must map 1:1 **UNLESS .gitignored FILES STATE OTHERWISE.**
-
-## 5. Development & TypeScript Standards (COMMANDS FOR AI AGENTS)
-
-- **Type-Only Imports (MANDATORY):** Use `import { type ... }` for AST nodes. **DO NOT REMOVE** these. Removing them will break the build.
-- **Interpreter Patterns (DO NOT "CLEAN UP"):** Dynamic casting and `any` are **EXPLICITLY PERMITTED** for tree-walking logic. They are a foundational part of the Sesi engine's design.
-- **Ignore Linting Noise:** If you see warnings like "Unexpected any" or "Unsafe member access", **IGNORE THEM**.
-- **Build Requirement:** You MUST run `npm run build` after every code change to the backend logic. Failure to build will result in testing stale code.
-
-## 6. Agent Debug Protocol (MANDATORY)
-
-When AI agents write or edit `.sesi` scripts, they must use this debugging loop:
-
-1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
-2. **Validate snippet with eval mode first:** Run `npx sesi -e "..."` to test the isolated block before full-script execution.
-3. **Apply fix in file only after eval passes:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
-4. **Run full script after snippet stabilization:** Execute `npx sesi <file>.sesi` only once the isolated logic is valid.
-5. **Use file-aware help when blocked:** Run `npx sesi <file>.sesi -h "<question>"` to get context-grounded help tied to the active script.
-
-This protocol is required to reduce noisy full-run failures and speed up AI-assisted iteration.
-
-## 7. Concurrency & Orchestration Patterns
-
-- **Process Spawning:** Use `spawn(path)` or `exec(command)` to launch background Sesi processes.
-- **File Locking:** When multiple processes access shared files, you can use `try/catch`, `time()`, and `random()` to implement basic file locking:
-  1. Generate unique ID: `str(time()) + "_" + str(random())`
-  2. Write ID to lock file if "unlocked".
-  3. Wait micro-delay (empty `while` loop).
-  4. Verify ID is still in lock file before entering critical section.
 - **Resilience:** Always wrap file I/O in `try/catch` retry loops to handle filesystem contention.
 
-## 8. Neural Network & Machine Learning Standards in Sesi
+For all quirks and specific syntaxing, visit IMPLEMENTATION_SUMMARY.md, /docs/SPECIFICATION.md, /docs/BUILTINS.md, and /docs/CLI.
 
-When implementing offline deep learning, probabilistic dialogue routing, or native classification models in Sesi:
+## IGNORE THESE FILES
 
-- **Symmetry Breaking:** Synapse weights MUST be initialized dynamically using wide, random float ranges (e.g. `(random() * 4.0) - 2.0` or `random() - 0.5`) to avoid zero-gradient stagnation and guarantee symmetry breaking.
-- **The Self-Healing Watchdog Pattern:** In native Sesi training models, wrap backpropagation epochs inside a conditional watchdog loop. Monitor the final Mean Squared Error (MSE) loss, and automatically re-seed weights and relaunch training if the network gets stuck in linear minima traps (e.g. `if MSE >= 0.01`).
-- **Unbreakable Markov Decoding Filters:** To eliminate infinite graph loops in Sesi probabilistic text walks, always apply:
-  1. **Extended Sliding Lookbacks (Size 15):** Instantly penalize and discard candidates already generated in the last 15 words of the sentence history.
-  2. **Strict Bigram Blocking:** Scan the history array and completely ban any candidate that repeats a previously executed state transition pair `(current_word -> candidate)` in the same sequence.
-- **Model Ingestion & Persistence:** Synchronize Sesi weights using natively parsed JSON objects. Save calibrated neural states directly using `write_file(..., to_json(weights_map))` and read them into runtime memories using `from_json(read_file(...))` for high-speed offline forward passes.
+- `docs/agent_native_programming.md`
+- `docs/REASONING.md`
+- `docs/IMAGE_GENERATION.md`
+- `*.txt`
+- `*.log`
+- `query.txt`
+- `.sesi_cache.json`
+- `.sesi_chat_history.json`
+- `/landing-pages/`

package/docs/SPECIFICATION.md

@@ -7,7 +7,7 @@ Sesi is built on these core principles:
 1. **Conciseness and Legibility**: The syntax is minimal. If a concept can be expressed simply, the language gets out of the way to let you express it.
 2. **Buildable from Scratch**: Sesi is a complete, functioning language with its own lexer, parser, and interpreter.
 3. **Simplicity Enables Power**: Because the core language is simple, complex operations (like hitting APIs or orchestrating processes) become trivial extensions of the language, rather than tangled SDK implementations.
-4. **Transparency Over Magic**: Sesi executes exactly what you write. 
+4. **Transparency Over Magic**: Sesi executes exactly what you write.
 5. **Practicality**: Focus on reducing boilerplate code, emphasizing what developers actually need over academic completeness.
 
 ## 2. Target Users
@@ -41,16 +41,16 @@ Sesi is built on these core principles:
 - ✅ Comments (`//`, `/* */`)
 - ✅ Operators (arithmetic, logical, comparison)
 - ✅ Standard library (print, len, range, etc.)
+- ✅ `prompt` blocks (composable templates for concise formatting)
+- ✅ `structured_output()` (schema-guided structured output with JSON recovery and empty-object fallback on failure)
+- ✅ `tool_call()` (Fully functional function calling for tool use)
+- ✅ `memory` (simple multi-turn script memory and retrieval context management)
 
 ### Reasoning-Native Features
 
-- ✅ `prompt` blocks (composable message templates)
 - ✅ `model()` calls (native model with configuration)
 - ✅ `image()` calls (native image generation with configuration)
 - ✅ `images` config key (multimodal vision input for `model()` and `image()`)
-- ✅ `structured_output()` (schema-guided structured output with JSON recovery and empty-object fallback on failure)
-- ✅ `tool_call()` (Fully functional function calling via models)
-- ✅ Simple memory (conversation context)
 
 ### Type System
 
@@ -178,7 +178,7 @@ Example:
 ```sesi
 for i = 0 to 10 {print i}
 try
-{let result = model("Hello")
+{let result = "Hello"
 } catch (e) {
 print e}
 ```
@@ -242,10 +242,10 @@ config_entry := (STRING | identifier) ':' expression
 | Key             | Applies to       | Type                      | Description                                                                |
 | --------------- | ---------------- | ------------------------- | -------------------------------------------------------------------------- |
 | `thinkingLevel` | `model`          | `string \| object`        | **Recommended**: Effort level (`"minimal"`, `"low"`, `"medium"`, `"high"`) |
-| `temperature`   | `model`, `image` | `number`                  | *Will be deprecated in Gemini 3.x+_ (Sampling temperature)                 |
+| `temperature`   | `model`, `image` | `number`                  | \*Will be deprecated in Gemini 3.x+\_ (Sampling temperature)               |
 | `max_tokens`    | `model`          | `number`                  | Max output token count                                                     |
-| `top_k`         | `model`          | `number`                  | *Will be deprecated in Gemini 3.x+_                                        |
-| `top_p`         | `model`          | `number`                  | *Will be deprecated in Gemini 3.x+_                                        |
+| `top_k`         | `model`          | `number`                  | \*Will be deprecated in Gemini 3.x+\_                                      |
+| `top_p`         | `model`          | `number`                  | \*Will be deprecated in Gemini 3.x+\_                                      |
 | `ratio`         | `image`          | `string`                  | Aspect ratio e.g. `"16:9"`                                                 |
 | `size`          | `image`          | `string`                  | `"512"`, `"1K"`, `"2K"`, `"4K"`                                            |
 | `images`        | `model`, `image` | `string \| array<string>` | Local file path(s) passed as visual input                                  |
@@ -267,13 +267,21 @@ schema := '{' (identifier ':' type (',' identifier ':' type)*)? '}'
 Example:
 
 ```sesi
-let analysis = structured_output({sentiment: string, score: number, keywords: array<string>})(model("gemini-3.1-flash-lite") { analyzeText })
+let rawJson = "{\"projectName\": \"Sesi\", \"version\": \"1.3.0\", \"status\": \"active\"}"
+let parsedRegistry = structured_output({projectName: string, version: string, status: string})(rawJson)
 ```
 
 #### Tool Call
 
 ```
-tool_call := 'tool_call' '('function_name')' '('model_call')'
+tool_call := 'tool_call' '('function_name')' '('(model_call | expressions)?')'
+```
+
+Example (Native Sandboxed Dispatch):
+
+```sesi
+fn add(a: number, b: number) -> number { return a + b }
+let sum = tool_call(add)(10, 20)
 ```
 
 #### Memory (State Management)
@@ -364,6 +372,10 @@ time() -> number                  // Current Unix timestamp
 random() -> number                // Random float (0.0 to 1.0)
 ```
 
+### Built-in Global Variables
+
+- `args` - `array<string>`: Contains the command-line arguments passed to the script, excluding Sesi runtime options and the script path.
+
 ## 9. Module System
 
 Runtime module execution and standard namespace modules are fully implemented and natively supported in v1.3+.
@@ -396,12 +408,12 @@ import json from "std/json"    // JSON parsing
 
 When you write `import {x} from "mymodule"`, Sesi searches for `mymodule.sesi` in the following order, stopping at the first match:
 
-| Priority | Location | Description |
-| -------- | -------- | ----------- |
-| 1 | **Script's own directory** | Same folder as the currently running `.sesi` file |
-| 2 | **Current working directory** | The directory you ran `sesi` from |
-| 3 | **`SESI_PATH`** | Semicolon-separated (Windows) or colon-separated (Unix) list of additional directories |
-| 4 | **`~/.sesi/lib`** | Global shared library directory — available system-wide |
+| Priority | Location                      | Description                                                                            |
+| -------- | ----------------------------- | -------------------------------------------------------------------------------------- |
+| 1        | **Script's own directory**    | Same folder as the currently running `.sesi` file                                      |
+| 2        | **Current working directory** | The directory you ran `sesi` from                                                      |
+| 3        | **`SESI_PATH`**               | Semicolon-separated (Windows) or colon-separated (Unix) list of additional directories |
+| 4        | **`~/.sesi/lib`**             | Global shared library directory — available system-wide                                |
 
 This means imports always resolve correctly regardless of where you run `sesi` from.
 
@@ -477,10 +489,10 @@ print "Image written to logo.png"
 - **`max_tokens`**: `number` (maximum response tokens)
 - **`images`**: `string` or `array<string>` (paths to multimodal vision input files)
 - **`cache`**: `bool` (set to `false` to explicitly bypass Sesi Logic Caching)
-- **`temperature`**: *  Will be deprecated in Gemini 3.x+, use thinkingLevel instead.* — reasoning is pre-optimized for defaults.
-- **`top_k` / `top_p`**: *Will be deprecated in Gemini 3.x+, use thinkingLevel instead.* — reasoning is pre-optimized for defaults.
+- **`temperature`**: _ Will be deprecated in Gemini 3.x+, use thinkingLevel instead._ — reasoning is pre-optimized for defaults.
+- **`top_k` / `top_p`**: _ Will be deprecated in Gemini 3.x+, use thinkingLevel instead._ — reasoning is pre-optimized for defaults.
 
-### Structured Output
+### Reasoning with Structured Output
 
 ```sesi
 let result = structured_output({title: string, category: string, confidence: number})(model("gemini-3.1-flash-lite") {"Extract metadata from this text:" text})
@@ -488,7 +500,7 @@ print result.title       // Access fields
 print result.confidence  // Type-safe access
 ```
 
-### Tool Calling
+### Reasoning with Tool Calling
 
 ```sesi
 fn calculateTax(amount: number, rate: number) {print amount * rate}
@@ -496,7 +508,7 @@ let taxAmount = tool_call(calculateTax)(model("gemini-3.1-flash-lite") {"Calcula
 taxAmount
 ```
 
-### Memory
+### Reasoning with Memory
 
 ```sesi
 memory chat {"System: You are a helpful assistant."}
@@ -522,7 +534,7 @@ fn analyzeText(text: string) -> string {return model("gemini-3.5-flash") {thinki
 print analyzeText("Reasoning is transforming industries")
 ```
 
-### Example 3: Structured Output
+### Example 3: Reasoning with Structured Output
 
 ```sesi
 let sentiment = structured_output({label: string, score: number})(model("gemini-3-flash-preview") {"Analyze sentiment of:" userInput})

package/examples/03_functions.sesi

@@ -1,6 +1,35 @@
 // Functions
 fn add(a: number, b: number) {print a + b}
 fn greet(name: string = "World") {print "Hello" name "!"}
+
 add(5, 3)
 greet()
-greet("Alice")
+greet("Alice")
+
+// Advanced Functions
+fn calculate(operation: string, a: number, b: number) {
+    if operation == "add" {
+        print a + b
+    } else if operation == "subtract" {
+        print a - b
+    } else if operation == "multiply" {
+        print a * b
+    } else if operation == "divide" {
+        print a / b
+    } else {
+        print "Invalid operation"
+    }
+}
+
+calculate("add", 5, 3)
+
+// Define your functions and call it using a custom tool
+
+fn getSesiVersion() {
+    return "1.3.2"
+}
+
+define_tool("sesi", getSesiVersion, "Get the current Sesi version")
+let v = tool_call(sesi)()
+
+print "Current version:" v

package/examples/07_prompts.sesi

@@ -1,4 +1,4 @@
-// Prompt blocks - composable message templates
+// Prompt blocks - composable text templates
 prompt greetingTemplate {"Hello! " "How are you today?"}
 prompt responseTemplate {greetingTemplate " I hope you're having a great day!"}
 // Prompts evaluate to strings
@@ -7,4 +7,28 @@ print greeting
 // Prompts can use variables
 let userName = "Alice"
 prompt personalGreeting {"Hello, " userName "! Welcome back!"}
-print personalGreeting
+print personalGreeting
+
+// You can really explore the power of prompt blocks by using it to structure your outputs
+
+prompt htmlHead {"<!DOCTYPE html>
+<html lang='en'>
+<head>
+    <meta charset='UTF-8'>
+    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
+    <title>Document</title>
+</head>
+"}
+prompt htmlBody {"<body>
+    <h1>Hello World!</h1>
+    <p>This is a paragraph</p>
+</body>
+"}
+prompt htmlFooter {"</html>"}
+prompt htmlLayout {htmlHead htmlBody htmlFooter}
+try {
+    write_file("index.html", htmlLayout)
+    print "HTML file created successfully!"
+} catch(error) {
+    print "Error creating HTML file: " error
+}

package/examples/08_model_call.sesi

@@ -1,5 +1,7 @@
 // Reasoning-powered text analysis using model calls
-// Requires GEMINI_API_KEY environment variable
-let text = "Artificial intelligence is transforming how we work and live"
-let analysis = model("gemini-3.1-flash-lite") {temperature: 0.5, max_tokens: 400} {"Analyze the following text and provide 3 concise key insights. Keep the total response under 120 words. " text}
-print "Analysis:" analysis
+// USING IT FOR AI IS OPTIONAL AND NOT REQUIRED TO USE IN YOUR SCRIPTS.
+// COMMENTED OUT BECAUSE AI WILL FORCE THEMSELVES TO RUN IT
+
+// let text = "Sesi is transforming how we work and live"
+// let analysis = model("gemini-3.1-flash-lite") {temperature: 0.5, max_tokens: 400} {"Analyze the following text and provide 3 concise key insights. Keep the total response under 120 words. " text}
+// print "Analysis:" analysis

package/examples/09_structured_output.sesi

@@ -1,7 +1,23 @@
 // Sentiment analysis with structured output
-// Requires GEMINI_API_KEY environment variable
+// THIS IS OPTIONAL AND NOT REQUIRED TO USE IN YOUR SCRIPTS.
+
 let review = "This product is amazing! I love how it works. Highly recommended!"
 let sentiment = structured_output({sentiment: string, confidence: number, keywords: string})(model("gemini-3.1-flash-lite") {"Analyze the sentiment of this review and extract key information. Return JSON with: sentiment (positive/negative/neutral), confidence (0-1), keywords (comma-separated) " review})
 print "Sentiment:" sentiment["sentiment"]
 print "Confidence:" sentiment["confidence"]
-print "Keywords:" sentiment["keywords"]
+print "Keywords:" sentiment["keywords"]
+
+// Structured output can be used without model() function as well
+// For example, if you have an API endpoint that returns JSON data, you can use structured_output to parse it.
+
+let json_data = web_get("https://jsonplaceholder.typicode.com/todos/1")
+let structured_data = structured_output({title: string, completed: boolean})(json_data)
+print "Title:" structured_data["title"]
+print "Completed:" structured_data["completed"]
+
+// You can even pass raw text to structured_output if you want, it just needs to be in JSON format. For example:
+
+let raw_text = "{\"title\": \"Buy milk\", \"completed\": false}"
+let structured_data = structured_output({title: string, completed: boolean})(raw_text)
+print "Title:" structured_data["title"]
+print "Completed:" structured_data["completed"]

package/examples/10_code_generation.sesi

@@ -1,5 +1,7 @@
 // Code generation with Reasoning
-// Requires GEMINI_API_KEY environment variable
-let requirement = "A function that checks if a number is prime"
-let generatedCode = model("gemini-3.1-flash-lite") {temperature: 0.2, max_tokens: 500} {"Generate JavaScript code for the following requirement: " requirement " Provide only the code, no explanation."}
-print "Generated Code:" generatedCode
+// USING IT FOR AI IS OPTIONAL AND NOT REQUIRED TO USE IN YOUR SCRIPTS.
+// COMMENTED OUT BECAUSE AI WILL FORCE THEMSELVES TO RUN IT
+
+// let requirement = "A function that checks if a number is prime"
+// let generatedCode = model("gemini-3.1-flash-lite") {temperature: 0.2, max_tokens: 500} {"Generate JavaScript code for the following requirement: " requirement " Provide only the code, no explanation."}
+// print "Generated Code:" generatedCode

package/examples/11_memory_conversation.sesi

@@ -1,16 +1,48 @@
-// Multi-turn conversation with memory
-// Requires GEMINI_API_KEY environment variable
-memory conversation {"You are a helpful programming assistant. Respond concisely."}
-fn askBot(question: string) -> string {
-  let message = conversation + "User:" + question
-  let response = model("gemini-3.1-flash-lite") {message}
-  conversation = message + "Assistant:" + response
-  return response
+// You can use memory to store variables throughout your script without redeclaring it
+
+memory store_database {"name: string, age: number, role: string"}
+
+store_database = {"name": "John", "age": 30, "role": "developer"}
+print "Name:" store_database["name"]
+print "Age:" store_database["age"]
+print "Role:" store_database["role"]
+try {
+  write_file("data.txt", to_json(store_database))
+  print "Database saved!"
+} catch(error) {
+  print "Error:" error
 }
-print "Starting conversation..."
-let answer1 = askBot("What is a closure in JavaScript?")
-print "Q1 Answer:" answer1
-let answer2 = askBot("Can you give me an example?")
-print "Q2 Answer:" answer2
-let answer3 = askBot("How do I use it in practice?")
-print "Q3 Answer:" answer3
+
+let new_info = {"name": "Jane", "age": 25, "role": "designer"}
+let merged = store_database
+for key in keys(new_info) {
+  merged[key] = new_info[key]
+}
+store_database = merged
+print "Name:" store_database["name"]
+print "Age:" store_database["age"]
+print "Role:" store_database["role"]
+try {
+  write_file("data.txt", to_json(store_database))
+  print "Database updated!"
+} catch(error) {
+  print "Error:" error
+}
+
+// USING IT FOR AI IS OPTIONAL AND NOT REQUIRED TO USE IN YOUR SCRIPTS.
+// COMMENTED OUT BECAUSE AI WILL FORCE THEMSELVES TO RUN IT
+
+// memory conversation {"You are a helpful programming assistant. Respond concisely."}
+// memory conversationfn askBot(question: string) -> string {
+//  let message = conversation + "User:" + question
+//  let response = model("gemini-3.1-flash-lite") {message}
+//  conversation = message + "Assistant:" + response
+//  return response
+//}
+// print "Starting conversation..."
+// let answer1 = askBot("What is a closure in JavaScript?")
+// print "Q1 Answer:" answer1
+// let answer2 = askBot("Can you give me an example?")
+// print "Q2 Answer:" answer2
+// let answer3 = askBot("How do I use it in practice?")
+// print "Q3 Answer:" answer3

package/examples/12_classification.sesi

@@ -1,8 +1,63 @@
-// Data classification using Reasoning
-// Requires GEMINI_API_KEY environment variable
+// Data classification 
+
 let items = ["A quick brown fox", "123 Main Street", "user@example.com", "New York City"]
-fn classifyItem(item: string) -> string {return model("gemini-3.1-flash-lite") {"Classify this item into one of: TEXT, ADDRESS, EMAIL, LOCATION " "Item: " item}}
-print "Classifying items..."
-for item in items 
-{let classification = classifyItem(item)
-print item "->" classification}
+
+fn isEmail(item: string) -> bool {
+  let parts = split(item, "@")
+  if len(parts) != 2 {
+    return false
+  }
+  let localPart = parts[0]
+  let domainPart = parts[1]
+  if len(localPart) == 0 || len(domainPart) == 0 {
+    return false
+  }
+  let domainParts = split(domainPart, ".")
+  if len(domainParts) < 2 {
+    return false
+  }
+  for part in domainParts {
+    if len(part) == 0 {
+      return false
+    }
+  }
+  return true
+}
+
+fn isAddress(item: string) -> bool {
+  // Simplified check for address-like strings
+  let parts = split(item, " ")
+  // Must contain numbers and words
+  let hasNumber = false
+  let hasWord = false
+  for part in parts {
+    if num(part) != null {
+      hasNumber = true
+    } else if len(part) > 1 {
+      hasWord = true
+    }
+  }
+  return hasNumber && hasWord && len(parts) >= 2
+}
+
+print "Classifying items natively:"
+for item in items {
+  if isEmail(item) {
+    print item "-> EMAIL"
+  } else if isAddress(item) {
+    print item "-> ADDRESS"
+  } else {
+    print item "-> TEXT/LOCATION"
+  }
+}
+
+// USING AI IS OPTIONAL AND NOT REQUIRED TO USE IN YOUR SCRIPTS.
+// COMMENTED OUT BECAUSE AI WILL FORCE THEMSELVES TO RUN IT
+
+
+// let items = ["A quick brown fox", "123 Main Street", "user@example.com", "New York City"]
+// fn classifyItem(item: string) -> string {return model("gemini-3.1-flash-lite") {"Classify this item into one of: TEXT, ADDRESS, EMAIL, LOCATION " "Item: " item}}
+// print "Classifying items..."
+// for item in items 
+// {let classification = classifyItem(item)
+// print item "->" classification}