@misterscan/sesi 1.3.0 → 1.3.3

package/docs/QUICKSTART.md

@@ -5,12 +5,19 @@
 Once Sesi is installed, you can run Sesi files globally:
 
 ```bash
-sesi main/start.sesi
+sesi examples/01_hello.sesi
+```
+
+You can also pass arguments to your script, which are exposed under the global `args` array:
+
+```bash
+sesi main/test_args.sesi arg1 arg2
 ```
 
 ### Run Tests
 
 For devs working on Sesi, you can verify your backend edits with the built-in test suite:
+
 ```bash
 npm test
 ```
@@ -19,8 +26,10 @@ npm test
 
 Create a file called `hello.sesi`:
 
-```sesi
-print "Hello, Sesi!"
+```bash
+sesi -e 'let txt = "Hello, world!"
+prompt file {"print \"" txt "\""}
+write_file("hello.sesi", file)'
 ```
 
 Run it:
@@ -84,6 +93,53 @@ let person = {"name": "Alice", "age": age}
 print person["name"] "is" person["age"] "years old."    // "Alice is 25 years old."
 ```
 
+Prompts are **composable message templates** that evaluate to strings. You can also utilize these to write clean and concise sesi scripts by nesting variables and even other prompts within prompts.
+
+### 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)
+```
+
+Structured output allows you to extract structured data natively or via Reasoning. It uses a JSON Schema to define the structure of the output.
+
+### Basic Structured Output
+
+```sesi
+let rawJson = "{\"projectName\": \"Sesi\", \"version\": \"1.3.0\", \"status\": \"active\"}"
+let analysis = structured_output({projectName: string, version: string, status: string})(rawJson)
+print "Project: " analysis["projectName"]
+print "Version: " analysis["version"]
+print "Status: " analysis["status"]
+```
+
 ## Reasoning Features
 
 ### Requiring Gemini API
@@ -111,15 +167,7 @@ let response = model("gemini-3-flash-preview") {temperature: 0.8, max_tokens: 10
 print response
 ```
 
-### Prompts
-
-```sesi
-let name = "Developer"
-prompt greeting {"Hello, " name "! " "How are you today?"}
-print greeting
-```
-
-### Structured Output
+### Reasoning with Structured Output
 
 ```sesi
 let analysis = structured_output({sentiment: string, score: number})(model("gemini-3.1-flash-lite") {"Analyze sentiment of: This product is great!"})
@@ -314,7 +362,7 @@ let rejoined = join(words, "-")
 ### Reasoning Classification
 
 ```sesi
-fn classify(item: string) 
+fn classify(item: string)
 {print model("gemini-3-flash-preview"){"Classify as: FRUIT, VEGETABLE, or GRAIN. Item: " item}}
 classify("apple")
 classify("carrot")
@@ -326,7 +374,7 @@ classify("wheat")
 ### Print Intermediate Values
 
 ```sesi
-fn complex(x: number) 
+fn complex(x: number)
 {let step1 = x * 2
 print "Step 1:" str(step1)
 let step2 = step1 + 10
@@ -365,6 +413,8 @@ else {print "Response: " response}
 3. **Understand architecture**: [ARCHITECTURE.md](docs/ARCHITECTURE.md)
 4. **Check roadmap**: [ROADMAP.md](docs/ROADMAP.md)
 5. **Study examples**: [examples/](examples/)
+6. **Understand the Agent-Native Paradigm**: [agent_native_programming.md](docs/agent_native_programming.md)
+7. **Read the historical Stress Test Chronicles**: [sesi_ai_chronicles.md](docs/sesi_ai_chronicles.md)
 
 ## Getting Help
 
@@ -380,30 +430,61 @@ sesi -h "how to spawn background processes?"
 You can also pass a file into the help context so the co-pilot can talk about that exact script:
 
 ```bash
-sesi main/playground.sesi -h
-sesi main/playground.sesi -h "why is this failing?"
+sesi examples/01_hello.sesi -h
+sesi examples/01_hello.sesi -h "what is this script doing?"
 ```
 
 Other useful CLI options:
 
 ```bash
-# Run a one-line snippet
+# Run a one-line snippet (inline)
 sesi -e "print 'hello'"
+```
 
-# Encrypt or decrypt a script file
-sesi -encrypt my_script.sesi -p "my-password"
-sesi -decrypt my_script.sesi -p "my-password"
+### Security & Sandboxing
+
+```bash
+# Encrypt or decrypt a script file (with password parameter)
+sesi -enc my_script.sesi -p "my-password"
+sesi -dec my_script.sesi -p "my-password"
+```
+
+To avoid exposing passwords in your shell's history, you can set the `SESI_PASSWORD` environment variable in your `.env` file (or your system's shell environment).
+
+```bash
+export SESI_PASSWORD="my-password"
+
+# Encrypt or decrypt automatically using SESI_PASSWORD environment variable
+sesi -enc my_script.sesi
+sesi -dec my_script.sesi
 
 # Disable sandbox protections for a run
-sesi main/start.sesi --local
+sesi examples/01_hello.sesi -l
 
 # Add extra allowed filesystem paths
-sesi main/start.sesi --allowed-paths ./docs,./examples
+sesi examples/01_hello.sesi -a ./docs,./examples
+```
+
+### Repository Script Shortcuts
+
+If working directly inside the Sesi codebase, you can use convenient npm shortcuts to run Sesi commands:
+
+```bash
+# Evaluate inline code
+npm run sesi:eval -- "print 'Hello from npm!'"
+
+# Encrypt / Decrypt files using SESI_PASSWORD environment fallback
+npm run sesi:encrypt -- "my_script.sesi"
+npm run sesi:decrypt -- "my_script.sesi"
+
+# Search with Sesi's Co-Pilot
+npm run sesi:help -- "how do I use multi_req()?"
 ```
 
 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
@@ -420,4 +501,4 @@ When reporting bugs:
 
 ---
 
-Happy programming with Sesi! 🚀
+Happy programming with Sesi! 🚀

package/docs/README.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="favicon.ico" alt="Sesi Logo" height="100" />
-</p>
-
 <h1 align="center">Sesi: A Concise, Legible Programming Language</h1>
 
 <p align="center">
@@ -16,20 +12,25 @@
 </p>
 
 <p align="center">
-  <strong>Sesi</strong> 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.
+  <strong>Sesi</strong> is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. It is a language built for clarity.
 </p>
 
 <p align="center">
   <a href="https://code-with-sesi.netlify.app/">Homepage</a>
 </p>
 
+## SESI IS **NOT** AN AI WRAPPER LANGUAGE. IT IS **NOT** AN AI-NATIVE PROGRAMMING LANGUAGE. IT IS A GENERAL-PURPOSE PROGRAMMING LANGUAGE WITH **OPTIONAL** AI CAPABILITIES BUILT-IN. STRONG EMPHASIS ON **OPTIONAL**.
+
 ## Quick Start
 
 Run any program directly:
 
 ```bash
 # Standard script execution
-sesi main/start.sesi
+sesi examples/01_hello.sesi
+
+# Run script with arguments
+sesi main/test_args.sesi arg1 arg2
 
 # Reasoning script example
 sesi examples/08_model_call.sesi
@@ -43,28 +44,67 @@ Useful CLI shortcuts:
 ```bash
 # Evaluate a quick snippet
 sesi -e "print 'hello'"
+```
 
+```bash
 # Ask the built-in co-pilot a question
-sesi -help "how do I use memory?"
+sesi -h "how do I use memory?"
+```
 
+```bash
 # Ask for help about a specific file
-sesi main/playground.sesi -h "why is this failing"
+sesi examples/01_hello.sesi -h "what is this script doing?"
+```
 
-# Encrypt or decrypt a script file
-sesi -encrypt my_script.sesi -p "my-password"
-sesi -decrypt my_script.sesi -p "my-password"
+```bash
+# Encrypt or decrypt a script file manually
+sesi -enc my_script.sesi -p "my-password"
+sesi -dec my_script.sesi -p "my-password"
+```
 
+To avoid exposing passwords in your shell's history, you can set the `SESI_PASSWORD` environment variable in your `.env` file (or your system's shell environment).
+
+```bash
+export SESI_PASSWORD="my-password"
+# Encrypt or decrypt automatically using SESI_PASSWORD environment variable
+sesi -enc my_script.sesi
+sesi -dec my_script.sesi
+```
+
+```bash
 # Run with sandbox restrictions disabled
-sesi main/start.sesi --local
+sesi examples/01_hello.sesi -l
 ```
 
 # Local Execution (Development)
 
-If you choose not use the `sesi` command, use the helper npm scripts:
+If you are developing inside the repository or haven't installed `sesi` globally, use the npm scripts:
+
+```bash
+# Run a Sesi script
+npm run sesi -- examples/01_hello.sesi
+```
+
+```bash
+# Evaluate an inline snippet
+npm run sesi:eval -- "print 'Sesi running!'"
+```
+
+```bash
+# Ask Sesi's Co-Pilot
+npm run sesi:help -- "how to make a directory?"
+```
+
+```bash
+# Encrypt / Decrypt scripts (uses SESI_PASSWORD from your .env automatically)
+npm run sesi:encrypt -- "secret.sesi"
+npm run sesi:decrypt -- "secret.sesi"
+```
 
 ```bash
-npm run example 01_hello.sesi
-npm run example:ai 08_model_call.sesi
+# Run classic examples
+npm run example examples/01_hello.sesi
+npm run example:ai examples/08_model_call.sesi
 npm run example:all
 ```
 
@@ -95,13 +135,13 @@ print code
 
 ## Security & Sandboxing
 
-Sesi is designed to run and orchestrate untrusted AI reasoning pipelines. Because code can be influenced by prompt injections or generated model instructions, Sesi incorporates a **safe-by-default, zero-trust sandboxing engine**.
+Sesi incorporates a **safe-by-default, zero-trust sandboxing engine**.
 
 ### 🛡️ Core Security Features
 
 1. **Safe-by-Default Execution**:
    - Sesi's sandbox is **enabled by default**. Any standard Sesi interpreter execution blocks system command lines (`exec`, `spawn`) and locks down imports and paths.
-   - *Overriding Safety:* Developers can explicitly bypass safe mode programmatically by initializing the interpreter with options, or on the command line by setting `SESI_SAFE_MODE=false`.
+   - _Overriding Safety:_ Developers can explicitly bypass safe mode programmatically by initializing the interpreter with options, or on the command line by setting `SESI_SAFE_MODE=false`.
 
 2. **Absolute Prototype Pollution Immunity**:
    - Sesi uses **prototype-free objects (`Object.create(null)`)** for all object literals, JSON parses (`from_json` or `std/json`), and structured model responses inside the interpreter.
@@ -118,36 +158,38 @@ Sesi is designed to run and orchestrate untrusted AI reasoning pipelines. Becaus
    - Sub-interpreters loaded via concurrent workflows (`multi_req`) are fully isolated. Sesi **deep-clones** prompts and memories, preventing concurrent agent tasks from leaking state or polluting each other.
 
 ### ⚙️ Programmatic Embedding Configurations
+
 When embedding Sesi inside a host application, you can statically configure safety settings directly in code:
+
 ```typescript
 const interpreter = new Interpreter(scriptDir, {
-  safeMode: true,        // Enable full sandbox limits (on by default)
-  allowLocalFs: false,  // Block directory escapes (on by default)
-  allowedPaths: ['/var/tmp/sandbox'] // Custom strict whitelist directories
+  safeMode: true, // Enable full sandbox limits (on by default)
+  allowLocalFs: false, // Block directory escapes (on by default)
+  allowedPaths: ["/var/tmp/sandbox"], // Custom strict whitelist directories
 });
 ```
 
 ## Documentation
 
-- [Getting Started](https://github.com/Misterscan/Sesi/blob/main/QUICKSTART.md)
+- [Getting Started](./QUICKSTART.md)
 - [Examples](./examples/)
-- [Language Specification](https://github.com/Misterscan/Sesi/blob/main/docs/SPECIFICATION.md)
-- [Language Comparison Showcase](https://github.com/Misterscan/Sesi/blob/main/docs/COMPARISON.md)
-- [Built-in Functions](https://github.com/Misterscan/Sesi/blob/main/docs/BUILTINS.md)
-- [Reasoning Guide](https://github.com/Misterscan/Sesi/blob/main/docs/REASONING.md)
-- [Concurrency Systems](https://github.com/Misterscan/Sesi/blob/main/docs/CONCURRENCY.md)
-- [Runtime Architecture](https://github.com/Misterscan/Sesi/blob/main/docs/ARCHITECTURE.md)
+- [CLI Reference](./docs/CLI.md)
+- [Language Specification](./docs/SPECIFICATION.md)
+- [Language Comparison Showcase](./docs/COMPARISON.md)
+- [Built-in Functions](./docs/BUILTINS.md)
+- [Reasoning](./docs/REASONING.md)
+- [Concurrency Systems](./docs/CONCURRENCY.md)
+- [Runtime Architecture](./docs/ARCHITECTURE.md)
 
 ## 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/`.
+The root-level `SKILLS.md` file is a workspace context file for AI agents.
 
 ## 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
@@ -171,20 +213,18 @@ Sesi/
 │   └── sesi.js                      # CLI executable
 │
 ├── main/                            # Playgrounds & debugging
-│   ├── playground.sesi              # Main playground script
-│   ├── start.sesi                   # Beginner script
 │   └── tests/                       # Additional syntax validation scripts
 │
 ├── docs/
+│   ├── CLI.md                       # Comprehensive CLI & Parametric Eval guide
 │   ├── SPECIFICATION.md             # Complete language spec (600+ lines)
 │   ├── ARCHITECTURE.md              # Runtime & system design (400+ lines)
 │   ├── BUILTINS.md                  # Built-in functions reference (450+ lines)
 │   ├── COMPARISON.md                # Language comparison showcase
-│   ├── CONCURRENCY.md               # Concurrency & coordination guide (>100 lines)
 │   ├── IMAGE_GENERATION.md          # Image generation guide (>100 lines)
 │   ├── REASONING.md                 # Reasoning and simple logic guide (>500 lines)
-│   ├── ROADMAP.md                   # V2-V4+ development plan (400+ lines)
-│   └── sesi_ai_chronicles.md        # AI project history & notes
+│   └── ROADMAP.md                   # V2-V4+ development plan (400+ lines)
+│
 │
 ├── examples/
 │   ├── 01_hello.sesi                # Hello World
@@ -239,19 +279,21 @@ Sesi/
 
 ### 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
+- **Async Polling**: Native looping to auto-resume generation when hitting `MAX_TOKENS` limit
+
+### System Features ✅
+
+- **Memory**: Basic memory for multi-turn reasoning
+- **Filesystem I/O**: `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
+- **Structured Output**: `structured_output()` for typed JSON Schema
+- **Function Calling**: `tool_call()` for function calling
+- **Prompt Blocks**: `prompt` blocks for cleaner and more concise script composition
 
 ### Type System
 
@@ -276,4 +318,4 @@ Sesi/
 
 ## License
 
-MIT
+MIT

package/docs/REASONING.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-In Sesi, Reasoning is used to evaluate state, make logical decisions, and handle complex patterns. This guide covers how to leverage Sesi's built-in Reasoning functions (`model`, `image` `prompt`, `structured_output`, `tool_call`) to build scripts for your designated needs.
+In Sesi, Reasoning is used to evaluate state, make logical decisions, and handle complex patterns. This guide covers how to leverage Sesi's built-in Reasoning functions (`model`, `image`, `workflow`) to build scripts for your designated needs.
 
 ## 1. Prompting
 
@@ -62,8 +62,9 @@ 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)*
+// - max_tokens: max length of response (OPTIONAL: if not specified, will use the model's default max tokens=4096)
+// - temperature: creative variation (OPTIONAL: defaults to 0.1 for high-fidelity reasoning precision)
+// - top_k / top_p: parameter options for specialized sampling configurations
 ```
 
 ### Model Selection
@@ -126,7 +127,7 @@ 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."}
+let result = model("gemini-3.5-flash") {images: scannedDocument, thinkingLevel: "low", max_tokens: 4096} {"Transcribe all text visible in this scan."}
 write_file("transcript.txt", result)
 ```
 
@@ -178,13 +179,12 @@ Let Reasoning call functions in your program.
 ```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} 
+{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
@@ -419,7 +419,7 @@ print response
 
 ```sesi
 // Bad: Same analysis done multiple times
-for person in people 
+for person in people
 {let assessment = model("gemini-3.1-flash-lite") {"Assess based on criteria A, B, C: "  person}}
 print assessment
 
@@ -428,7 +428,7 @@ print assessment
 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 
+for person in people
 {print assessPerson(person)}
 ```
 
@@ -463,7 +463,7 @@ fn smartSummarize(text: string) -> string
 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} 
+let summary = model("gemini-3-flash-preview") {"Summarize with topics " topics ": " keyPoints}
 return summary}
 print "Summary:" smartSummarize(text)
 ```
@@ -517,7 +517,7 @@ print answer
 Sesi allows you to define custom tools that can be invoked during reasoning operations.
 
 ```sesi
-fn get_weather(city: string, conditions: string) -> string 
+fn get_weather(city: string, conditions: string) -> string
 {return "It is currently " + conditions + " in " + city}
 // Register the tool
 define_tool("weather", get_weather, "Get weather for a city")
@@ -535,10 +535,15 @@ print result
 
 ## See Also
 
-- [Compare to other languages](COMPARISON.md)
+- [Quick Start Guide](../QUICKSTART.md)
 - [Language Specification](SPECIFICATION.md)
-- [Image Generation](IMAGE_GENERATION.md)
-- [Architecture](ARCHITECTURE.md)
-- [Built-ins](BUILTINS.md)
-- [Examples](../examples/)
-- [Roadmap](ROADMAP.md)
+- [Runtime Architecture](ARCHITECTURE.md)
+- [Built-in Functions Reference](BUILTINS.md)
+- [Command Line Interface (CLI) Reference](CLI.md)
+- [Image Generation & Input](IMAGE_GENERATION.md)
+- [Compare to other languages](COMPARISON.md)
+- [Concurrency & Coordination](CONCURRENCY.md)
+- [Reasoning & Simple Logic](REASONING.md)
+- [Agent-Native Programming Paradigm](agent_native_programming.md)
+- [Historical Stress Test Chronicles](sesi_ai_chronicles.md)
+- [Examples](../examples)

package/docs/ROADMAP.md

@@ -398,10 +398,15 @@ The journey from v1 (interpreter) to v4+ (distributed compiler) maintains backwa
 
 ## See Also
 
-- [Specification](SPECIFICATION.md)
-- [Architecture](ARCHITECTURE.md)
-- [Built-ins](BUILTINS.md)
-- [Process Execution](PROCESS_EXECUTION.md)
-- [Image Generation](IMAGE_GENERATION.md)
+- [Quick Start Guide](../QUICKSTART.md)
+- [Language Specification](SPECIFICATION.md)
+- [Runtime Architecture](ARCHITECTURE.md)
+- [Built-in Functions Reference](BUILTINS.md)
+- [Command Line Interface (CLI) Reference](CLI.md)
+- [Image Generation & Input](IMAGE_GENERATION.md)
 - [Compare to other languages](COMPARISON.md)
+- [Concurrency & Coordination](CONCURRENCY.md)
+- [Reasoning & Simple Logic](REASONING.md)
+- [Agent-Native Programming Paradigm](agent_native_programming.md)
+- [Historical Stress Test Chronicles](sesi_ai_chronicles.md)
 - [Examples](../examples)