@misterscan/sesi 1.1.1 → 1.2.0

package/docs/QUICKSTART.md

@@ -1,32 +1,6 @@
 # Quick Start Guide: Sesi Programming Language
 
-## Installation
-
-### Prerequisites
-
-- Node.js 18+
-- npm or yarn
-
-### Setup
-
-1. **Clone and install**:
-
-```bash
-git clone https://github.com/Misterscan/Sesi.git
-cd sesi-programming-lang
-npm install
-
-# Unlock the `sesi` command
-npm install -g
-```
-
-2. **Build from TypeScript**:
-
-```bash
-npm run build
-```
-
-3. **Run a program (if installed globally)**:
+## Run a program:
 
 ```bash
 sesi main/start.sesi
@@ -189,9 +163,14 @@ print "Both workers are now running concurrently."
 ```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
@@ -217,6 +196,24 @@ 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:
@@ -236,6 +233,16 @@ 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
@@ -324,16 +331,28 @@ else {print "Response: " response}
 
 ## 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/)
+1. **Read the spec**: [SPECIFICATION.md](SPECIFICATION.md)
+2. **Learn about reasoning**: [SYSTEMS_REASONING.md](SYSTEMS_REASONING.md)
+3. **Understand architecture**: [ARCHITECTURE.md](ARCHITECTURE.md)
+4. **Check roadmap**: [ROADMAP.md](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/)
+- Review examples in [examples/](/examples/)
 - Read error messages carefully
 - Try simpler programs first
 

package/docs/README.md

@@ -19,31 +19,7 @@
 
 ## Quick Start
 
-# Global Installation (Recommended)
-
-Clone the repository:
-
-```bash
-git clone https://github.com/Misterscan/Sesi.git
-cd sesi-programming-lang
-```
-You'll need a [Gemini API Key](https://aistudio.google.com/app/apikey). Create a `.env` file referencing your key:
-
-```env
-GEMINI_API_KEY="AIzaSy..."
-```
-
-You can install Sesi globally to use the `sesi` command anywhere on your system:
-
-```bash
-# Install required dependencies
-npm install
-
-# Unlock the `sesi` command
-npm install -g .
-```
-
-Then run any program directly:
+Run any program directly:
 
 ```bash
 # Standard script execution
@@ -58,7 +34,7 @@ sesi examples.sesi
 
 # Local Execution (Development)
 
-If you choose not install `sesi` globally, use the helper npm scripts:
+If you choose not use the `sesi` command, use the helper npm scripts:
 
 ```bash
 npm run example 01_hello.sesi
@@ -93,14 +69,14 @@ print code
 
 ## Documentation
 
-- [Getting Started](QUICKSTART.md)
+- [Getting Started](./QUICKSTART.md)
 - [Examples](./examples/)
-- [Language Specification](SPECIFICATION.md)
-- [Language Comparison Showcase](COMPARISON.md)
-- [Built-in Functions](BUILTINS.md)
-- [Reasoning Guide](.SYSTEMS_REASONING.md)
-- [Distributed Systems](DISTRIBUTED_SYSTEMS.md)
-- [Runtime Architecture](ARCHITECTURE.md)
+- [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
 
@@ -109,7 +85,7 @@ The root-level `SKILLS.md` file is a workspace context file for AI agents. It re
 ## Project Structure
 
 ```
-sesi-programming-lang/
+Sesi/
 ├── SKILLS.md             # AI-agent workspace context and repo guardrails
 ├── index.html            # Sesi-generated landing page
 ├── eslint.config.mjs     # ESLint configuration
@@ -130,7 +106,7 @@ sesi-programming-lang/
 │   └── index.ts          # Main entry point
 ├── bin/
 │   └── sesi.js           # CLI executable
-├── examples/             # 15 sample programs demonstrating all features
+├── examples/             # 18 sample programs demonstrating all features
 ├── main/                 # Main entry and specialized tests
 │   ├── playground.sesi   # Main playground script
 │   ├── start.sesi        # Beginner script 
@@ -140,7 +116,7 @@ sesi-programming-lang/
 └── docs/                 # Documentation (ARCHITECTURE, BUILTINS, SPECIFICATION, etc.)
 ```
 
-## Version 1.1 Features (Complete)
+## Version 1.2 Features (In Progress)
 
 ### Core Language ✅
 
@@ -149,6 +125,11 @@ sesi-programming-lang/
 - **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 ✅
 
@@ -159,7 +140,10 @@ sesi-programming-lang/
 - `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 Orchestration**: `spawn()` and `exec()` for concurrent process management
+- **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
 
@@ -174,8 +158,6 @@ sesi-programming-lang/
 ### V2: Advanced Reasoning
 
 - Long-term memory and context management
-- Parallel model calls
-- Advanced error handling with Reasoning fallbacks
 - Custom tool definitions
 - Streaming responses
 

package/docs/ROADMAP.md

@@ -51,20 +51,19 @@
 - No async/await
 - Blocking Reasoning calls
 - Limited error messages
-- No module system (imports/exports planned)
 - No pattern matching
 - No generics or custom types
 
 ---
 
-## Version 1.1 - Stability & Systems Logic (Complete)
+## Version 1.2 - Stability & Systems Logic (In Progress)
 
-**Status**: Complete V1.1 implementation  
+**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 ✅
+### Improvements & Features ⌛
 
 - [x] Systems Builtins: `spawn`, `exec`, `time`, `random`
 - [x] Concurrency: Async polling via file locks for completion and MAX_TOKENS
@@ -99,14 +98,14 @@
 ### Async/Await Support
 
 - [ ] async/await syntax (language level)
-- [ ] Parallel reasoning calls (native)
+- [x] Parallel reasoning calls (native)
 - [ ] Promise-like operations
 - [x] Concurrent execution (Multi-process via `spawn`)
 
 ### Advanced Reasoning Features
 
 - [ ] Streaming responses
-- [ ] Extended thinking/reasoning budget
+- [x] Extended thinking/reasoning budget
 - [ ] Multi-step reasoning workflows
 - [ ] Tool composition and piping
 - [ ] Custom tool definitions
@@ -131,7 +130,7 @@
 ### Performance
 
 - [ ] Bytecode compilation
-- [ ] Logic caching
+- [x] Logic caching
 - [ ] Token counting and cost estimation
 - [ ] Lazy evaluation
 
@@ -142,12 +141,12 @@
 - [ ] Math functions (sqrt, sin, cos, floor, ceil, etc.)
 - [ ] Date/time functions
 - [ ] JSON parsing and serialization
-- [ ] HTTP client (get, post)
+- [x] HTTP client (get, post)
 
 ### Module System
 
-- [ ] import/export statements
-- [ ] Standard library modules (std/math, std/time, etc.)
+- [x] import/export statements
+- [x] Standard library modules (std/math, std/time, etc.)
 - [ ] Third-party package management
 - [ ] Namespace support
 
@@ -273,7 +272,7 @@
 
 ```
 2026 Q2
-└─ v1.1 - Polish & stabilize
+└─ v1.2 - Polish & stabilize
 
 2026 Q3-Q4
 └─ v2.0 - Advanced Reasoning & async

package/docs/SPECIFICATION.md

@@ -1,4 +1,4 @@
-# Sesi Systems Language Specification (v1.1)
+# Sesi Systems Language Specification (v1.2)
 
 ## 1. Philosophy & Design Principles
 
@@ -27,7 +27,7 @@ Sesi is built on these core principles:
 - Concurrent process management and distributed locking
 - Multi-stage reasoning workflows with stateful memory
 
-## 3. V1.1 Feature Set (Current)
+## 3. V1.2 Feature Set (Current)
 
 ### Core Language Features
 
@@ -47,6 +47,7 @@ Sesi is built on these core principles:
 - ✅ `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)
@@ -222,17 +223,28 @@ prompt codeReview {"Review this code for bugs:" code "Provide specific issues fo
 #### Model & Image Calls
 
 ```
-model_call := 'model' '('STRING')' '{'config (optional)'}' '{'prompt'}'
-            | 'model' '('STRING')' '{'prompt'}'
-image_call := 'image' '('STRING')' '{'config (optional)'}' '{'prompt'}'
-            | 'image' '('STRING')' '{'prompt'}'
-config := ((STRING | identifier) ':' expression (',' (STRING | identifier) ':' expression)*)?
+model_call := 'model' '('STRING')' config_block? '{'prompt'}'
+image_call := 'image' '('STRING')' config_block? '{'prompt'}'
+config_block := '{' config_entry (',' config_entry)* '}'
+config_entry := (STRING | identifier) ':' expression
 ```
 
+**Config keys:**
+
+| Key | Applies to | Type | Description |
+|-----|-----------|------|-------------|
+| `temperature` | `model`, `image` | `number` | Sampling temperature (0.0–1.0) |
+| `max_tokens` | `model` | `number` | Max output token count |
+| `top_k` | `model` | `number` | Top-K diversity |
+| `top_p` | `model` | `number` | Nucleus sampling |
+| `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 |
+
 Example:
 
 ```sesi
-let result = model("gemini-3.1-flash-lite") {codeReview}
+let result = model("gemini-3-flash-preview") {images: "scan.png", temperature: 0} {"Transcribe all visible text."}
 let output = model("gemini-3.1-flash-lite") {"temperature": 0.4, "max_tokens": 2000} {prompt}
 ```
 
@@ -283,7 +295,7 @@ optional_type := type '?'
 
 1. **Short-circuit evaluation**: `&&` and `||` short-circuit
 2. **Type coercion**: Automatic for numeric operations; explicit for string/number
-3. **Null propagation**: Operations on `null` return `null` (no exceptions in v1.1)
+3. **Null propagation**: Operations on `null` return `null` (no exceptions in v1.2)
 4. **Model responses**: Always returned as strings initially; structured_output provides type safety
 
 ## 6. Scope and Binding
@@ -345,7 +357,7 @@ random() -> number                // Random float (0.0 to 1.0)
 
 ## 9. Module System
 
-Parser support for `import` / `export` syntax exists in v1.1, but runtime module execution is not implemented yet.
+Runtime module execution and standard namespace modules are fully implemented and natively supported in v1.1.2.
 
 ### Defining Modules
 
@@ -378,15 +390,18 @@ import json from "std/json"    // JSON parsing
 Prompts are composable message templates:
 
 ```sesi
-prompt translate {"Translate the following to Spanish:" sourceText}
+prompt translate {"translate the following to Spanish:" sourceText}
 prompt summarize {"Summarize this in 3 sentences:" text}
-prompt combined {summarize "Now translate:" translate}
+prompt combined {summarize " Now " translate}
 ```
 
 ### Model & Image Calls
 
+Model calls can take optional configuration parameters (written on a single line) followed by one or more prompts/strings.
+
 ```sesi
-let response = model("gemini-3-flash-preview") {"temperature": 0} {"Say hello"}
+// Model call with temperature and thinking scale configuration
+let response = model("gemini-3.1-pro-preview") {"thinkingLevel": {"thinking": "yes", "level": "low"}, "temperature": 0} {"Say hello"}
 print response  // Returns string
 
 let logo = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "512"} {"A vector logo"}
@@ -394,6 +409,14 @@ write_image("logo.png", logo)
 print "Image written to logo.png"
 ```
 
+#### Config Block Options:
+- **`temperature`**: `number` (0.0 to 1.0)
+- **`max_tokens`**: `number` (maximum response tokens)
+- **`images`**: `string` or `array<string>` (paths to multimodal vision input files)
+- **`thinkingLevel`**: `object` with keys `"thinking"` (`"yes"` | `"no"`) and `"level"` (`"low"` | `"medium"` | `"high"`) - natively configures and scales Gemini's reasoning budget.
+- **`cache`**: `bool` (set to `false` to explicitly bypass Sesi Logic Caching)
+
+
 ### Structured Output
 
 ```sesi
@@ -444,7 +467,7 @@ print sentiment.label
 print sentiment.score
 ```
 
-## 12. Undefined Behavior & Limitations (V1.1)
+## 12. Undefined Behavior & Limitations (V1.2)
 
 - **No async/await**: All operations within a script are blocking (including model calls). Concurrency must be achieved via `spawn()`.
 - **No custom types**: Only built-in types are supported natively.

package/docs/SYSTEMS_REASONING.md

@@ -86,7 +86,7 @@ print greeting  // "Hello, Alice! How are you?"
 
 ```sesi
 prompt part1 {"First part"}
-prompt part2 {part1 " " "Second part"}
+prompt part2 {part1 " Second part"}
 print part2  // "First part Second part"
 ```
 
@@ -96,7 +96,7 @@ print part2  // "First part Second part"
 let text = "Testing"
 let language = "Spanish"
 fn translatePrompt(text: string, language: string) -> string
-{prompt translate {"Translate the following text to "language": " text} return translate}
+{prompt translate {"Translate " text " to " language ": "} return translate}
 print translatePrompt(text, language)
 ```
 
@@ -129,7 +129,7 @@ print creative
 ```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}
+let quick = model("gemini-3-flash-preview") {"Summarize this in one sentence:" text}
 
 // Powerful model for complex reasoning
 let code = "def calculate_sum(n):
@@ -148,16 +148,16 @@ print smart
 print cheap
 ```
 
-### Available Models (v1.1)
+### 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` - Legacy, but reliable.
+- `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, 1M tokens
-- `gemini-3.1-pro-preview` - Most capable, 1M tokens
+- `gemini-3.1-pro-preview` - Most capable, 1M tokens (Doesn't support `minimal` thinking. Only `low`, `medium`, and `high` are supported.)
 - `gemini-3.1-flash-lite` - Fastest, cost-efficient
 - `gemini-3.1-flash-image-preview` - Cost efficient while maintaining quality images.
-- `gemini-3-pro-image-preview` - High quality image generation.
+- `gemini-3-pro-image-preview` - High quality image generation. (No `512` image size support for this model.)
 
 #### Planned for (v2+)
 
@@ -166,6 +166,29 @@ print cheap
 - `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.1-flash-lite") {images: scannedDocument, temperature: 0, 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.
@@ -346,6 +369,8 @@ write_image("logo.png", logo)
 print "Image generated!"
 ```
 
+![Sesi Logo](logo.png)
+
 ### Code Generation
 
 ```sesi
@@ -371,7 +396,7 @@ print analyzeSentiment(text)
 
 Reasoning operations can fail. Handle gracefully.
 
-### Try/Catch (v1.1)
+### Try/Catch (v1.2)
 
 ```sesi
 try
@@ -492,11 +517,10 @@ let summary = model("gemini-3-flash-preview") {"Summarize with topics " topics "
 print "Summary:" smartSummarize(text)
 ```
 
-### Reasoning Pattern (V2: native support)
+### Reasoning Pattern
 
 ```sesi
-// Future: Extended thinking
-let analysis = model("gemini-3-flash-preview") {"temperature": 0, "thinking_level": "low"} {"Reason carefully about:" problem}
+let analysis = model("gemini-3-flash-preview") {"thinkingLevel": {"thinking": "yes", "level": "medium"}, "temperature": 0, "max_tokens": 8192} {"Reason carefully about:" problem}
 print analysis
 ```