@misterscan/sesi 1.1.1

package/docs/QUICKSTART.md

@@ -0,0 +1,351 @@
+# 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)**:
+
+```bash
+sesi main/start.sesi
+```
+
+### Run Tests
+
+```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
+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
+```
+
+### 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]
+```
+
+## 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
+```
+
+## 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
+
+- 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! 🚀

package/docs/README.md

@@ -0,0 +1,191 @@
+<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>
+
+**Sesi** is a high-performance **Systems Language** 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.
+
+## 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:
+
+```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](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)
+
+## 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-programming-lang/
+├── 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/             # 15 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.1 Features (Complete)
+
+### 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.
+
+### 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 Orchestration**: `spawn()` and `exec()` for concurrent process management
+- **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
+- Parallel model calls
+- Advanced error handling with Reasoning fallbacks
+- Custom tool definitions
+- Streaming responses
+
+### V3: Agents & Orchestration
+
+- Agent definitions with state
+- Tool composition and chaining
+- Multi-agent collaboration
+- Persistent knowledge bases
+
+## License
+
+MIT