Metadata-Version: 2.4
Name: baobab-lang
Version: 0.1.0
Summary: Baobab: the French-first programming language - bao CLI (run, translate, build, test, format)
Author-email: Seidy KANTE <seidy@baobablang.dev>
License-Expression: MIT
Project-URL: Homepage, https://www.baobablang.dev
Project-URL: Documentation, https://www.baobablang.dev/docs
Project-URL: Repository, https://github.com/baobablang/baobab
Keywords: baobab,bao,langage,francais,french,education,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: Software Development :: Compilers
Classifier: Natural Language :: French
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn>=0.30; extra == "server"
Requires-Dist: websockets>=13; extra == "server"
Requires-Dist: pybars3>=0.9; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: prod
Requires-Dist: psycopg[binary]>=3.2; extra == "prod"
Requires-Dist: redis>=5; extra == "prod"
Dynamic: license-file

<div align="center">

# 🌳 Baobab

**Learn to program in French - and read like Python underneath.**

Write `fonction`, `si`, `pour`, `afficher`. Baobab transpiles to standard Python and runs on CPython, so you keep the entire Python ecosystem with virtually no runtime overhead.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python](https://img.shields.io/badge/Python-3.13+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org) [![FastAPI](https://img.shields.io/badge/API-FastAPI-009688.svg?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com) [![Tests](https://img.shields.io/badge/tests-conformance%20suite-brightgreen.svg)](tests/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

[**Website**](https://baobablang.dev) · [**Documentation**](https://baobablang.dev/docs) · [**Playground**](https://baobablang.dev/playground) · [**Studio (web IDE)**](https://github.com/baobablang/baobab-studio)

</div>

---

## Why Baobab?

Most beginners fight two battles at once: **learning to program** and **learning English keywords**. Baobab removes the second while preserving Python's exact semantics. Once you're comfortable in Baobab, the move to Python is almost mechanical.

> Baobab is **not** Python translated into French. It is a programming language designed around French vocabulary that stays **fully compatible with Python** a gateway into real programming, not a walled garden.

> **Naming:** **Baobab** is the programming language (and the wider ecosystem [baobablang.dev](https://baobablang.dev)). **Bao** is its short name: the `.bao` file extension and the `bao` CLI - like _Py_ for Python. **Baobab Studio** is the web IDE.

## What is Baobab?

- ✔ A programming language with **French vocabulary** and **Python semantics**
- ✔ **Transpiles to standard Python** - runs on CPython, virtually no overhead
- ✔ **Bidirectional** translation: Baobab → Python to run, Python → Baobab to learn
- ✔ A **`bao` CLI** and a **sandboxed runtime** with tracebacks shown _in Baobab_
- ✔ A **platform API** (execution, projects, auth) and an optional AI assistant
- ✔ **MIT open source**, bilingual (French / English)

This repository is the **reference implementation** of the Baobab language.

## See it

<table>
<tr><th>Baobab</th><th>Python</th></tr>
<tr valign="top"><td>

```python
fonction fibonacci(n):
    suite = [0, 1]
    tantque longueur(suite) < n:
        suite.ajouter(suite[-1] + suite[-2])
    retourner suite

afficher(fibonacci(10))
```

</td><td>

```python
def fibonacci(n):
    suite = [0, 1]
    while len(suite) < n:
        suite.append(suite[-1] + suite[-2])
    return suite

print(fibonacci(10))
```

</td></tr>
</table>

Both print `[0, 1, 1, 2, 3, 5, 8, 13, 21, 34]`.

It is not a mini-language nearly all of Python is there: conditionals, functions, classes, exceptions and context managers all have a direct Baobab form.

```python
fonction est_pair(n):
    retourner n % 2 == 0

classe Animal:
    fonction nouveau(nom):
        ce.nom = nom

essayer:
    x = entier(entree)
attraper ErreurValeur:
    afficher("Nombre invalide")

avec ouvrir("notes.txt") comme f:
    afficher(f.lire())
```

## Is Baobab a real programming language?

**Yes**. Baobab has its own vocabulary, documentation, CLI, runtime and conformance suite. It is precise about _how_ it runs your code:

- Baobab is a **transpiler** (a source-to-source compiler): it rewrites Baobab into Python and lets CPython execute the result.
- It is **not** an interpreter, and there is **virtually no runtime overhead** execution goes `Baobab → Python → CPython`, the same engine every Python program uses.

See [Implementation](#implementation) for the details of how the transpiler works.

## The language

- **French vocabulary, Python semantics.** Same indentation, same behavior only the surface words change. When in doubt, Baobab does what Python does.
- **Accent-free & typable.** The vocabulary avoids accents (`inserer`, `cles`, `trie`, `ErreurCle`…) so it works on any keyboard; sample identifiers follow PEP 8 ASCII. Accents live only in strings and prose.
- **Strict by design.** Running a `.bao` file that uses a Python word with a Baobab spelling (`return`, `while`, `print`…) is refused pointing you at the right word.
- **Bilingual runtime messages.** Errors and diagnostics follow the platform language (`fr` / `en`).

## The CLI

```bash
bao run main.bao                      # execute a Baobab program
bao translate main.bao --to python    # show the Python translation
bao build            # transpile a project      bao test     # run project tests
bao format src/      # format Baobab sources        bao --help   # every command
```

## The runtime

Programs run in a **sandbox**: an isolated subprocess with CPU/file output resource limits, a wall-clock timeout, a stripped environment (user code cannot read your secrets) and a **seccomp network block** (no sockets → no exfiltration).
Tracebacks are rewritten into **Baobab** French error names and your own source lines, not the generated Python.

> [!WARNING]
> The bundled subprocess sandbox is hardened for a trusted/beta setting but is **not sufficient for fully-public untrusted multi-tenant traffic**. Before an open launch, execution must move into per-run, network-isolated containers behind the same `run_project` / `run_interactive` interface. Do not expose arbitrary code execution publicly without that layer.

## The platform API

A **FastAPI** service on top of the language:

- **Execution** - `POST /api/run` and an interactive WebSocket (`/api/run/ws`) for programs that read input (`lire()`), auth-gated.
- **Translation** - `POST /api/translate` (Baobab ↔ Python).
- **Projects** - CRUD, folders, ZIP export, public share links.
- **Auth** - register + email OTP, login, password reset/change, sessions, rate limiting.
- **Billing** - plans, entitlements, metered usage, Stripe checkout/portal/webhook.

## AI assistant

A **bonus** layer, not what makes Baobab unique: an agentic, streaming assistant (`/api/ai/agent`) that returns file actions applied to the workspace. It supports **bring-your-own provider** (Ollama / OpenAI / Anthropic / Gemini) and is grounded in the language reference via **RAG**. A managed ("Pro") tier uses server-side keys.

## Architecture

```
                     Baobab Studio  (web IDE - separate repo)
                            │  HTTPS / WSS
                     FastAPI backend  (this repo)
                   ┌────────┴─────────┐
              Transpiler          AI agent (RAG)
                   │
                Python
                   │
              CPython runtime  (sandboxed)
```

The **Baobab vocabulary source of truth** lives in the frontend(`baobab-reference.ts`); `lang/vocabulary.py` mirrors it, and the **conformance suite** runs every reference and IDE example on **both** the Baobab and Python side, asserting identical output - so the docs and the language stay provably in sync.

## Quick start

> **Requirements:** Python **3.13+** (Baobab relies on the 3.12+ f-string tokenizer).
> Everything installs into a local `./.venv` - never the system Python.

```bash
git clone https://github.com/baobablang/baobab.git
cd baobab

python3.13 -m venv .venv
.venv/bin/pip install -e ".[dev,server]"
```

> **CLI only?** The `bao` command is 100% stdlib - once published,
> `pipx install baobab-lang` installs it with zero dependencies; the API
> server ships as the `[server]` extra (`pip install "baobab-lang[server]"`).

Run your first program:

```bash
.venv/bin/bao run examples/hello.bao          # execute a Baobab program
.venv/bin/bao translate examples/hello.bao    # see the Python translation
```

Start the API and developer tasks:

```bash
make dev      # API with reload → http://localhost:8000
make check    # CI gate: lint + format check + tests
make help     # every developer task
```

The defaults are zero-infra (SQLite, no Redis). `pip install -e ".[server,prod]"` adds PostgreSQL + Redis drivers; `make up-data` starts them via Docker.

## Project layout

```
src/baobab/
├── lang/        # vocabulary tables · token-level transpiler · diagnostics
├── runtime/     # sandboxed executor · French stdlib (afficher, ouvrir, maths…)
├── cli.py       # the `bao` command
├── api/         # FastAPI app: run · translate · projects · auth · billing · AI
├── services/    # ai (agent + RAG) · auth · projects · billing · export · otp
└── core/        # config · dual-dialect DB (SQLite/Postgres) · Redis · messages
tests/           # unit · conformance (the docs ARE the contract) · API tests
```

## Implementation

Baobab ships **no** hand-written lexer, parser or AST. Instead it reuses **CPython's own tokenizer**: it tokenizes your Baobab source, rewrites the French tokens to their Python equivalent (`fonction` → `def`, `afficher` → `print`, …), and hands the result to CPython. This guarantees exact Python-semantics parity and keeps the transpiler small and auditable. The reverse direction (Python → Baobab) works the same way and preserves comments and formatting.

> A richer Lark-based grammar (with a real AST and Baobab-native diagnostics carrying line/column spans) is on the roadmap. Today's token-level transpiler is intentionally simple and exact.

## Roadmap

> Ordered by the mission - beginners learning to program in French - not by
> engineering convenience. Full canonical roadmap: [`ROADMAP.md`](../ROADMAP.md).

**Shipped**

- [x] Baobab ↔ Python transpiler (bidirectional, formatting-preserving)
- [x] French-first runtime & sandbox (rlimits + seccomp + memory/fork-bomb guards) with Baobab tracebacks
- [x] `bao` CLI (run / translate / build / test / format) + the `baobab` alias
- [x] Platform API (execution + interactive WS, projects, auth, billing)
- [x] AI assistant (agentic, streaming; BYO provider + managed Pro)
- [x] Conformance suite (docs = contract)
- [x] The book - *« Apprendre la programmation avec Baobab »*
- [x] Pedagogical French error messages - an "error explainer" (French explanation + fix hint) for common syntax & runtime mistakes

**Now - learning experience & reach**

- [ ] CLI public distribution - `pipx install baobab-lang` on PyPI + one-line installer
- [ ] VS Code extension (highlighting & snippets → Run button → LSP)

**Next**

- [ ] In-browser execution (Pyodide / WASM) - free-tier runs client-side
- [ ] Visual output - turtle graphics (`tortue`)
- [ ] Interactive in-Studio tutorial
- [ ] Lark grammar + AST + Baobab-native diagnostics (line/column)
- [ ] Shareable / embeddable runnable snippets

**Later**

- [ ] Classroom / teacher features (assignments, auto-grading, progress)
- [ ] Per-run container sandbox for fully-public execution at scale
- [ ] Debugger + deeper editor tooling
- [ ] Mobile experience
- [ ] Package manager (`bao install`) + community registry
- [ ] Independent runtime (long-term, low priority - Python is an asset)

## Contributing

Contributions are welcome - newcomers included. Please read **[CONTRIBUTING.md](CONTRIBUTING.md)**; it covers the setup, the CI gate, and the few rules that keep the language coherent. By participating you agree to our [Code of Conduct](CONTRIBUTING.md#code-of-conduct).

## Acknowledgements

- Inspired by the _spirit_ of Ruslan Spivak's [**Let's Build A Simple Interpreter**](https://ruslanspivak.com/lsbasi-part1/) - the idea that building a language should be approachable. _(Baobab takes a transpiler approach rather than a tree-walking interpreter.)_
- Thanks to my friend [**Bedru**](https://github.com/bedre7) and his [**Abugida**](https://github.com/bedre7/abugida), a kindred educational language.

## License

Released under the [**MIT License**](LICENSE) · © 2026 [Wontan SAS](https://wontan.tech). Created by **Seidy KANTE**.

<div align="center"><sub>Part of the <a href="https://github.com/baobablang">Baobab</a> ecosystem · <a href="https://baobablang.dev">baobablang.dev</a></sub></div>
