Initial implementation of gendo: an LLM-based programming language

.cursor/rules/development-workflow.mdc

@@ -0,0 +1,36 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Development Workflow Guide
+
+## Building and Testing
+The project uses Make for build automation. Common tasks are defined in the [Makefile](mdc:Makefile):
+
+```bash
+make        # Build the project
+make test   # Run tests
+make bench  # Run benchmarks
+make deps   # Install dependencies
+```
+
+## Tool Development
+When implementing new tools:
+
+1. Define the tool struct and interface implementation in `pkg/tools/[toolname]/[toolname].go`
+2. Follow the Tool interface defined in [pkg/tools/tool.go](mdc:pkg/tools/tool.go)
+3. Write tests in `pkg/tools/[toolname]/[toolname]_test.go`
+4. Example: [pkg/tools/math/math.go](mdc:pkg/tools/math/math.go)
+
+## Testing Guidelines
+- Write unit tests for all new functionality in `pkg/tools/[toolname]/[toolname]_test.go`
+- Include benchmarks for performance-critical operations
+- Use table-driven tests where appropriate
+- Example: [pkg/tools/rand/rand.go](mdc:pkg/tools/rand/rand.go)
+
+## Code Organization
+- Keep tool implementations modular and focused
+- Follow Go best practices and idioms
+- Use meaningful package names and file structure
+- Example: [pkg/tools/math/math.go](mdc:pkg/tools/math/math.go)

.cursor/rules/git-commit-practices.mdc

@@ -0,0 +1,5 @@
+---
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/llm-integration.mdc

@@ -0,0 +1,33 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# LLM Integration Guide
+
+## Overview
+The project uses Language Model (LLM) integration for processing. The core components are:
+
+## LLM Interface
+- [pkg/llm/llm.go](mdc:pkg/llm/llm.go) defines the LLM interface and registry
+- All LLM implementations must implement the Process method
+- Registry pattern allows multiple LLM backends
+
+## OpenAI Implementation
+- [pkg/llm/openai/openai.go](mdc:pkg/llm/openai/openai.go) provides OpenAI integration
+- Handles API communication and response parsing
+- Supports environment-based configuration
+
+## Integration Guidelines
+When implementing new LLM providers:
+
+1. Create a new package under `pkg/llm/`
+2. Implement the LLM interface
+3. Handle API keys and configuration securely
+4. Follow the OpenAI implementation as a reference
+
+## Usage Example
+```go
+llm := openai.New(apiKey)
+response, err := llm.Process(systemPrompt, userInput)
+```

.cursor/rules/math-tool.mdc

@@ -0,0 +1,85 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Math Tool Implementation Guide
+
+The math tool in [pkg/tools/math/math.go](mdc:pkg/tools/math/math.go) provides mathematical expression parsing and calculation capabilities for the Gendo runtime. This guide outlines key implementation details and testing requirements.
+
+## Core Components
+
+### Expression Extraction
+The tool extracts mathematical expressions from natural language input through these key functions:
+
+1. `extractFirstExpression`: Main entry point that handles:
+   - Natural language prefixes (e.g., "What is")
+   - Quoted expressions
+   - Word-based operators
+   - Multiple expression formats
+
+2. `tryExtractExpression`: Low-level parser that:
+   - Handles numeric values and operators
+   - Maintains expression validity
+   - Removes unnecessary punctuation
+   - Preserves negative numbers
+
+3. `convertWordOperators`: Converts natural language operators to symbols:
+   - "plus" → "+"
+   - "minus" → "-"
+   - "times" or "multiplied by" → "*"
+   - "divided by" → "/"
+
+### Expression Parsing
+The `parseExpression` function handles:
+- Operator precedence
+- Multiple operators
+- Decimal numbers
+- Error conditions
+
+## Testing Requirements
+
+All changes must be verified through [pkg/tools/math/math_test.go](mdc:pkg/tools/math/math_test.go). Test cases must cover:
+
+1. Natural Language Processing:
+   - Prefixes ("What is")
+   - Suffixes ("equals", "is")
+   - Word operators
+   - Mixed formats
+
+2. Mathematical Operations:
+   - Basic arithmetic
+   - Negative numbers
+   - Decimal values
+   - Multiple operators
+
+3. Error Handling:
+   - Invalid expressions
+   - Division by zero
+   - Missing operators
+   - Invalid numbers
+
+## Integration Testing
+
+The calculator example in [examples/calculator.gendo](mdc:examples/calculator.gendo) serves as an integration test. Changes must be verified by running:
+
+```bash
+echo 'What is 1+1?' | ./gendo --verbose examples/calculator.gendo
+```
+
+## Development Guidelines
+
+1. Follow TDD practices:
+   - Write tests first
+   - Verify edge cases
+   - Maintain test coverage
+
+2. Error Handling:
+   - Return meaningful error messages
+   - Validate input thoroughly
+   - Handle edge cases gracefully
+
+3. Code Organization:
+   - Keep functions focused and single-purpose
+   - Document complex logic
+   - Use clear variable names

.cursor/rules/project-structure.mdc

@@ -0,0 +1,30 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Project Structure Guide
+
+## Overview
+Gendo is a Go-based tool system with modular architecture. The main components are:
+
+## Core Components
+- [pkg/tools/tool.go](mdc:pkg/tools/tool.go) - Defines the core Tool interface and Registry
+- [pkg/llm/llm.go](mdc:pkg/llm/llm.go) - Language Model interface and Registry
+- [pkg/llm/openai/openai.go](mdc:pkg/llm/openai/openai.go) - OpenAI LLM implementation
+
+## Tools
+The tools package contains various tool implementations:
+
+### I/O Tools
+- [pkg/tools/io/io.go](mdc:pkg/tools/io/io.go) - File reading and writing tools
+- [pkg/tools/io/io_test.go](mdc:pkg/tools/io/io_test.go) - Tests and benchmarks for I/O tools
+
+### Math Tools
+- [pkg/tools/math/math.go](mdc:pkg/tools/math/math.go) - Mathematical operations tool
+
+### Random Tools
+- [pkg/tools/rand/rand.go](mdc:pkg/tools/rand/rand.go) - Random number generation tool
+
+## Build System
+- [Makefile](mdc:Makefile) - Build automation and development tasks

.cursor/rules/testing-requirements.mdc

@@ -0,0 +1,63 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# Gendo Runtime Testing Requirements
+
+## Test-Driven Development
+
+All changes to the Gendo runtime must follow strict test-driven development practices:
+
+1. Write tests before implementing features
+2. Ensure all code paths are covered by tests
+3. Verify edge cases and error conditions
+4. Document test cases with clear descriptions
+
+## Testing Layers
+
+### Unit Tests
+- Each package must have comprehensive unit tests
+- Test files should be named `*_test.go`
+- Use table-driven tests for multiple test cases
+- Mock external dependencies appropriately
+
+### Integration Tests
+- Examples in [examples/](mdc:examples/) serve as integration tests
+- Do not modify example files unless updating the specification
+- Verify changes against example scripts
+- Use verbose logging for debugging
+
+### Runtime Verification
+- Build the project using `make`
+- Run example scripts to verify runtime behavior
+- Test with the local LLM endpoint (http://localhost:18080/v1)
+- Do not use external APIs or install new software
+
+## LLM Integration
+
+When testing LLM-related functionality:
+
+1. Use the local endpoint only
+2. Preserve complete prompt definitions
+3. Verify prompt construction
+4. Test error handling for LLM responses
+
+## Error Handling
+
+Test cases must verify:
+
+1. Invalid inputs
+2. Malformed scripts
+3. Network failures
+4. Resource limitations
+5. Edge cases in data processing
+
+## Documentation
+
+All test files must include:
+
+1. Clear test case descriptions
+2. Expected inputs and outputs
+3. Error conditions being tested
+4. Any special setup requirements

.github/copilot-instructions.md

@@ -0,0 +1,34 @@
+When reviewing code with GitHub Copilot, please ensure all code follows these fundamental principles. Every piece of 
+code must be implemented as a small, independent module with clear boundaries and responsibilities. Each module should 
+have a single, well-defined purpose and minimal dependencies on other modules.
+
+All code must be accompanied by comprehensive unit tests. Test files should be written before implementing features, 
+following test-driven development practices. Each test file must cover all code paths, including edge cases and error 
+conditions. Use table-driven tests for multiple test cases and mock external dependencies appropriately.
+
+Code organization is critical. Keep implementations modular and focused, following language-specific best practices and 
+idioms. Use meaningful package names and maintain a clear file structure. Each module should be self-contained and 
+easily testable in isolation.
+
+Error handling must be thorough and explicit. Test cases should verify invalid inputs, malformed data, network failures, 
+resource limitations, and edge cases in data processing. All error conditions must be properly documented and tested.
+
+Documentation is essential. All code must include clear descriptions of its purpose, expected inputs and outputs, error
+conditions, and any special setup requirements. Comments should explain why code is written a certain way, not what it
+does.
+
+When reviewing code, ensure that all dependencies are properly managed and that the code follows the project's
+established patterns and conventions. Code should be maintainable, readable, and follow the principle of least surprise.
+
+Integration tests are required for any code that interacts with external systems or other modules. These tests should 
+verify the correct behavior of the system as a whole, not just individual components.
+
+Performance considerations should be taken into account for any code that processes data or handles user interactions. 
+Include benchmarks for performance-critical operations and ensure that the code scales appropriately.
+
+Security is paramount. All code must be reviewed for potential security vulnerabilities, especially when handling user
+input or interacting with external systems. Follow the principle of least privilege and implement proper input 
+validation and sanitization.
+
+Remember that code quality is not just about functionality but also about maintainability, readability, and reliability.
+Every line of code should be written with these principles in mind.

.gitignore

@@ -1,3 +1,9 @@
+# Compiled gendo runtime
+gendo
+
+# Jetbrains configurations
+.idea
+
 # If you prefer the allow list template instead of the deny list, see community template:
 # https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
 #

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 HyperifyIO
+Copyright (c) 2025 Jaakko Heusala <jheusala@iki.fi>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -0,0 +1,55 @@
+.PHONY: all build test bench clean
+
+# Default target
+all: build
+
+# Build the project
+build:
+	@echo "Building..."
+	go build -o gendo ./cmd/gendo
+
+# Run all tests
+test:
+	@echo "Running tests..."
+	go test -v ./...
+
+# Run benchmarks
+bench:
+	@echo "Running benchmarks..."
+	go test -bench=. -benchmem ./...
+
+# Run tests with coverage
+coverage:
+	@echo "Running tests with coverage..."
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning..."
+	rm -f gendo
+	rm -f coverage.out
+
+# Install dependencies
+deps:
+	@echo "Installing dependencies..."
+	go mod download
+	go mod tidy
+
+# Run linter
+lint:
+	@echo "Running linter..."
+	golangci-lint run
+
+# Help target
+help:
+	@echo "Available targets:"
+	@echo "  all        - Build the project (default)"
+	@echo "  build      - Build the project"
+	@echo "  test       - Run all tests"
+	@echo "  bench      - Run benchmarks"
+	@echo "  coverage   - Run tests with coverage report"
+	@echo "  clean      - Remove build artifacts"
+	@echo "  deps       - Install dependencies"
+	@echo "  lint       - Run linter"
+	@echo "  help       - Show this help message"