Metadata-Version: 2.4
Name: stanstawalend
Version: 2026.1.0
Summary: A revolutionary natural language Python compiler — blend .sl instructions with Python code.
Home-page: https://github.com/octaveluka/stanstawalend
Author: Stanley Stawa
Author-email: Stanley Stawa <stanley.stawa@stanstawalend.dev>
License: MIT
Project-URL: Homepage, https://github.com/octaveluka/stanstawalend
Project-URL: Documentation, https://stanstawalend.dev/docs
Project-URL: Repository, https://github.com/octaveluka/stanstawalend
Project-URL: Issues, https://github.com/octaveluka/stanstawalend/issues
Keywords: compiler,natural-language,ai,python,dsl,stanstawalend
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=3.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: rich>=13.0.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# StanStawaLend 2026

> **Natural Language Python Compiler** — blend `.sl` instructions with pure Python code and let AI do the translation.

[![PyPI version](https://img.shields.io/badge/pypi-stanstawalend%202026.1.0-blue)](https://pypi.org/project/stanstawalend/)
[![Python](https://img.shields.io/badge/python-3.9%2B-brightgreen)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Author](https://img.shields.io/badge/Author-Stanley%20Stawa-purple)](https://github.com/octaveluka)

---

## What is StanStawaLend?

StanStawaLend is a **revolutionary programming paradigm** that lets you write `.sl` source files containing a mix of:

- **Standard Python code** — runs through as-is.
- **Natural-language instructions** prefixed with `~` — automatically translated to Python by AI.
- **Special @commands** prefixed with `~ @` — trigger powerful built-in tools (debug, fix, safe, undo, test…).

You write intent. StanStawaLend writes code.

---

## Installation

```bash
pip install stanstawalend
```

---

## Quick Start

### 1. Create a `.sl` file

```python
# my_program.sl

import random

~ Create a list of 10 random integers between 1 and 100
~ Sort that list in descending order
~ Print only the even numbers from the sorted list

~ @debug
~ @safe
```

### 2. Watch mode (live recompile on Ctrl+S)

```bash
stanstawalend watch my_program.sl
```

### 3. One-shot compile

```bash
stanstawalend compile my_program.sl -o output.py
```

### 4. Python API

```python
import stanstawalend

# Live watch
stanstawalend.watch("my_program.sl")

# One-shot
stanstawalend.compile_file("my_program.sl", output="output.py")
```

---

## How It Works

```
my_program.sl
│
├─ Pure Python lines ──────────────────────────────► passed through as-is
│
├─ ~ Natural language instruction ─► MD5 Cache? ──► hit: reuse
│                                     └─ Token Cache? ► hit: reuse
│                                         └─ AI API ───► generate & cache
│
└─ ~ @command ─────────────────────────────────────► @command handler
                                                        (debug/fix/safe/…)

Stawa_output.py ──► subprocess run ──► error? ──► Self-Healing (up to 3×)
```

### Incremental Compilation & Cache

Every `~` instruction is hashed (MD5). On the next save, only *changed* lines are re-translated. Unchanged lines are served from the local cache instantly — zero API calls.

```
.stanstawalend_cache/
├── line_cache.json      # MD5 hash → Python code
├── token_cache.json     # Instruction text → Python code (Token Saver)
└── history.json         # Undo stack (last 20 versions)
```

### Self-Healing

After every compile, StanStawaLend executes `Stawa_output.py` in a subprocess. If it crashes, the error + original code is sent back to the AI for automatic repair — up to **3 attempts**.

---

## @Commands Reference

| Command | Description |
|---|---|
| `~ @debug` | Analyse code and display an optimisation report |
| `~ @fix` | Force AI to detect and repair the current code |
| `~ @safe` | Sandbox scan for dangerous system calls |
| `~ @undo` | Restore the previous compiled version |
| `~ @explain` | Plain-language explanation of the program |
| `~ @test` | Generate pytest unit tests |
| `~ @run` | Execute output and display stdout/stderr |
| `~ @lint` | Syntax validation (ast.parse) |
| `~ @optimize` | Rewrite code for maximum performance |
| `~ @refactor` | Refactor for readability (PEP-8, type hints) |
| `~ @docs` | Add Google-style docstrings |
| `~ @types` | Add PEP-484 type annotations |
| `~ @vars` | List all variables in the generated context |
| `~ @summary` | One-paragraph description of the program |
| `~ @complexity` | Time and space complexity analysis |
| `~ @translate js` | Translate code to another language |
| `~ @benchmark` | Inject timeit benchmarking |
| `~ @profile` | Run cProfile and display top 20 entries |
| `~ @docker` | Generate a Dockerfile |
| `~ @ci` | Generate a GitHub Actions workflow |
| `~ @readme` | Generate a README.md |
| `~ @requirements` | Infer and write requirements.txt |
| `~ @redis` | Add Redis caching layer |
| `~ @json_api` | Add FastAPI REST layer |
| … | **100 commands total** — see `commands.py` |

---

## Example `.sl` File

```python
# data_processor.sl

import pandas as pd

~ Load a CSV file named 'sales.csv' into a DataFrame called df
~ Clean the DataFrame: drop rows with null values and reset the index
~ Add a new column 'revenue' = price * quantity
~ Group by 'category' and compute the mean revenue per group
~ Print the top 5 categories by mean revenue

~ @types
~ @docs
~ @test
~ @safe
```

StanStawaLend will:
1. Generate clean pandas code for each `~` instruction
2. Add type hints (`@types`)
3. Add docstrings (`@docs`)
4. Write a `Stawa_output_test.py` pytest file
5. Scan for dangerous patterns (`@safe`)

---

## Architecture

```
stanstawalend/
├── __init__.py      # Public API: watch(), compile_file()
├── __main__.py      # CLI: stanstawalend watch / compile
├── core.py          # Compilation engine, AI client, Self-Healing
├── watcher.py       # Real-time watchdog file monitor
└── commands.py      # Registry of 100 @commands
```

---

## Configuration

StanStawaLend uses the **Delfa AI endpoint** by default:

```
https://delfaapiai.vercel.app/ai/copilot?message={prompt}&model=default
```

You can override it in your code:

```python
from stanstawalend.core import AIClient, StawaCompiler

compiler = StawaCompiler()
compiler.ai = AIClient(endpoint="https://your-custom-endpoint.com/ai")
compiler.compile("myfile.sl")
```

---

## Requirements

- Python 3.9+
- `watchdog` ≥ 3.0
- `requests` ≥ 2.31
- `colorama` ≥ 0.4.6
- `rich` ≥ 13.0

---

## Author

**Stanley Stawa** — Creator of StanStawaLend  
GitHub: [@octaveluka](https://github.com/octaveluka)

---

## License

MIT © 2026 Stanley Stawa
