saturnolab 0.1.0__tar.gz

saturnolab-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.ipynb_checkpoints/
+frontend/node_modules/
+frontend/dist/
+saturnolab/static/
+.DS_Store

saturnolab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maicon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saturnolab-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: saturnolab
+Version: 0.1.0
+Summary: Lightweight JupyterLab-compatible Python notebook environment with native inline AI connected to live kernel memory.
+Project-URL: Homepage, https://github.com/maicondallg/saturnolab
+Project-URL: Repository, https://github.com/maicondallg/saturnolab
+Project-URL: Issues, https://github.com/maicondallg/saturnolab/issues
+Author: Maicon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,data-science,ipynb,jupyter,jupyterlab,llm,notebook,python
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: ipykernel>=6.29.0
+Requires-Dist: jupyter-client>=8.6.0
+Requires-Dist: nbformat>=5.10.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: data
+Requires-Dist: matplotlib>=3.8.0; extra == 'data'
+Requires-Dist: numpy>=1.26.0; extra == 'data'
+Requires-Dist: pandas>=2.0.0; extra == 'data'
+Requires-Dist: seaborn>=0.13.0; extra == 'data'
+Description-Content-Type: text/markdown
+
+# SaturnoLab
+
+**SaturnoLab** (`saturnolab`) is a fast, lightweight, `.ipynb`-compatible Python notebook environment built from the ground up with **Inline AI (`Ctrl+I` / `Ctrl+K`)** connected directly to live Python kernel memory.
+
+## Features
+
+- **100% `.ipynb` Compatible**: Open, edit, execute, and save standard Jupyter notebooks (`nbformat` v4).
+- **Zero-bloat Web UI**: Built with React, CodeMirror 6, and FastAPI (~305 KB gzipped) with 6 technical themes (*Graphite*, *Obsidian*, *Gruvbox*, *Nord*, *Jupyter Light*, *Warm Stone*).
+- **Inline Cell AI (`Ctrl+I` / `Ctrl+K`)**:
+  - Generate or edit Python code directly inside any cell or over a selected snippet.
+  - Automatically injects **live kernel variable schemas** (`DataFrame` shapes, column names, `dtypes`, array dimensions) and preceding cell context into the prompt.
+  - Instant `Tab` to accept, `Shift+Tab` to toggle *Replace* vs *Append*, and `Ctrl+Enter` to accept & execute immediately.
+- **Multi-Provider LLM Support**:
+  - **Google Gemini API** (`gemini-2.5-flash`, `gemini-2.5-pro`, etc.)
+  - **OpenAI Codex CLI / SDK** (`@openai/codex`)
+  - **OpenAI-compatible APIs** (OpenAI, local **Ollama**, OpenRouter, LM Studio)
+  - **Anthropic Claude API**
+- **Automatic Virtualenv Detection**: Automatically detects `.venv` / `venv` / `$VIRTUAL_ENV` in the target project folder.
+
+---
+
+## Installation
+
+```bash
+pip install saturnolab
+
+# Optional: include common data science stack (pandas, numpy, matplotlib, seaborn)
+pip install "saturnolab[data]"
+```
+
+Or install globally as an isolated CLI tool with **`uv`**:
+
+```bash
+uv tool install saturnolab
+```
+
+---
+
+## Usage
+
+Run `saturnolab` inside **any** project directory, just like `jupyter lab`:
+
+```bash
+# Open in the current directory
+saturnolab
+
+# Or point to any folder
+saturnolab /path/to/project
+
+# Custom port or headless server mode
+saturnolab --port 8900 --no-browser
+```
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl + I` or `Ctrl + K` | Open Inline AI inside active cell or selection |
+| `Shift + Tab` | Toggle between **Replace cell** and **Append to end** |
+| `Tab` / `Enter` | Accept generated code |
+| `Ctrl + Enter` | Run active cell (or Accept & Run in AI preview) |
+| `Shift + Enter` | Run active cell and advance |
+| `Alt + Enter` | Run active cell and insert new cell below |
+| `Alt + ↑ / ↓` | Move cell up / down |
+| `Ctrl + M` | Toggle cell between Python and Markdown |
+| `Ctrl + Shift + Backspace` | Delete active cell |
+| `Ctrl + S` | Save notebook |

saturnolab-0.1.0/README.md

@@ -0,0 +1,69 @@
+# SaturnoLab
+
+**SaturnoLab** (`saturnolab`) is a fast, lightweight, `.ipynb`-compatible Python notebook environment built from the ground up with **Inline AI (`Ctrl+I` / `Ctrl+K`)** connected directly to live Python kernel memory.
+
+## Features
+
+- **100% `.ipynb` Compatible**: Open, edit, execute, and save standard Jupyter notebooks (`nbformat` v4).
+- **Zero-bloat Web UI**: Built with React, CodeMirror 6, and FastAPI (~305 KB gzipped) with 6 technical themes (*Graphite*, *Obsidian*, *Gruvbox*, *Nord*, *Jupyter Light*, *Warm Stone*).
+- **Inline Cell AI (`Ctrl+I` / `Ctrl+K`)**:
+  - Generate or edit Python code directly inside any cell or over a selected snippet.
+  - Automatically injects **live kernel variable schemas** (`DataFrame` shapes, column names, `dtypes`, array dimensions) and preceding cell context into the prompt.
+  - Instant `Tab` to accept, `Shift+Tab` to toggle *Replace* vs *Append*, and `Ctrl+Enter` to accept & execute immediately.
+- **Multi-Provider LLM Support**:
+  - **Google Gemini API** (`gemini-2.5-flash`, `gemini-2.5-pro`, etc.)
+  - **OpenAI Codex CLI / SDK** (`@openai/codex`)
+  - **OpenAI-compatible APIs** (OpenAI, local **Ollama**, OpenRouter, LM Studio)
+  - **Anthropic Claude API**
+- **Automatic Virtualenv Detection**: Automatically detects `.venv` / `venv` / `$VIRTUAL_ENV` in the target project folder.
+
+---
+
+## Installation
+
+```bash
+pip install saturnolab
+
+# Optional: include common data science stack (pandas, numpy, matplotlib, seaborn)
+pip install "saturnolab[data]"
+```
+
+Or install globally as an isolated CLI tool with **`uv`**:
+
+```bash
+uv tool install saturnolab
+```
+
+---
+
+## Usage
+
+Run `saturnolab` inside **any** project directory, just like `jupyter lab`:
+
+```bash
+# Open in the current directory
+saturnolab
+
+# Or point to any folder
+saturnolab /path/to/project
+
+# Custom port or headless server mode
+saturnolab --port 8900 --no-browser
+```
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl + I` or `Ctrl + K` | Open Inline AI inside active cell or selection |
+| `Shift + Tab` | Toggle between **Replace cell** and **Append to end** |
+| `Tab` / `Enter` | Accept generated code |
+| `Ctrl + Enter` | Run active cell (or Accept & Run in AI preview) |
+| `Shift + Enter` | Run active cell and advance |
+| `Alt + Enter` | Run active cell and insert new cell below |
+| `Alt + ↑ / ↓` | Move cell up / down |
+| `Ctrl + M` | Toggle cell between Python and Markdown |
+| `Ctrl + Shift + Backspace` | Delete active cell |
+| `Ctrl + S` | Save notebook |

saturnolab-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "saturnolab"
+version = "0.1.0"
+description = "Lightweight JupyterLab-compatible Python notebook environment with native inline AI connected to live kernel memory."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Maicon" }
+]
+keywords = [
+    "jupyter",
+    "jupyterlab",
+    "notebook",
+    "ipynb",
+    "python",
+    "ai",
+    "llm",
+    "data-science",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: FastAPI",
+    "Framework :: Jupyter",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "websockets>=12.0",
+    "jupyter-client>=8.6.0",
+    "ipykernel>=6.29.0",
+    "nbformat>=5.10.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+]
+
+[project.optional-dependencies]
+data = [
+    "pandas>=2.0.0",
+    "numpy>=1.26.0",
+    "matplotlib>=3.8.0",
+    "seaborn>=0.13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/maicondallg/saturnolab"
+Repository = "https://github.com/maicondallg/saturnolab"
+Issues = "https://github.com/maicondallg/saturnolab/issues"
+
+[project.scripts]
+saturnolab = "saturnolab.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["saturnolab"]
+artifacts = ["saturnolab/static/**"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/saturnolab",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+artifacts = ["saturnolab/static/**"]

saturnolab-0.1.0/saturnolab/__init__.py

@@ -0,0 +1,3 @@
+"""SaturnoLab — Lightweight AI-first Python Notebook Environment."""
+
+__version__ = "0.1.0"

saturnolab-0.1.0/saturnolab/cli.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import argparse
+import os
+import socket
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from . import __version__
+
+
+def find_available_port(host: str, preferred_port: int, max_tries: int = 50) -> int:
+    for offset in range(max_tries):
+        port = preferred_port + offset
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind((host, port))
+                return port
+            except OSError:
+                continue
+    return preferred_port
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="saturnolab",
+        description="SaturnoLab — Ambiente leve de notebooks Python com IA Inline integrada ao Kernel.",
+    )
+    parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="Diretório do projeto para abrir no SaturnoLab (padrão: diretório atual).",
+    )
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=int(os.environ.get("SATURNOLAB_PORT", "8899")),
+        help="Porta HTTP inicial (padrão: 8899; avança automaticamente se ocupada).",
+    )
+    parser.add_argument(
+        "--host",
+        default=os.environ.get("SATURNOLAB_HOST", "127.0.0.1"),
+        help="Host para escutar conexões (padrão: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Não abrir o navegador automaticamente ao iniciar.",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="Habilitar auto-reload do servidor (desenvolvimento).",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"saturnolab {__version__}",
+    )
+
+    args = parser.parse_args(argv)
+
+    workspace_path = Path(args.directory).expanduser().resolve()
+    if not workspace_path.exists():
+        workspace_path.mkdir(parents=True, exist_ok=True)
+    elif not workspace_path.is_dir():
+        parser.error(f"O caminho informado não é um diretório: {workspace_path}")
+
+    os.environ["SATURNOLAB_WORKSPACE"] = str(workspace_path)
+
+    port = find_available_port(args.host, args.port)
+    url = f"http://{args.host}:{port}"
+
+    print(f"🪐 SaturnoLab v{__version__}")
+    print(f"📂 Diretório : {workspace_path}")
+    print(f"🌐 Servidor  : {url}")
+    print("   Pressione Ctrl+C para encerrar.\n")
+
+    if not args.no_browser:
+        def _open_browser() -> None:
+            time.sleep(0.8)
+            try:
+                webbrowser.open(url)
+            except Exception:
+                pass
+
+        threading.Thread(target=_open_browser, daemon=True).start()
+
+    uvicorn.run(
+        "saturnolab.main:app",
+        host=args.host,
+        port=port,
+        reload=args.reload,
+        log_level="warning",
+    )
+
+
+if __name__ == "__main__":
+    main()

saturnolab-0.1.0/saturnolab/config.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+CONFIG_DIR = Path.home() / ".saturnolab"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+LEGACY_CONFIG_FILE = Path.home() / ".saturno" / "config.json"
+
+VALID_THEMES = {
+    "graphite",
+    "obsidian",
+    "gruvbox",
+    "nord",
+    "paper",
+    "solarized_light",
+    "dark",
+    "light",
+}
+
+
+class ProviderSettings(BaseModel):
+    api_key: str = ""
+    model: str = ""
+    base_url: str = ""
+    reasoning_effort: str = "low"
+
+
+class SaturnoConfig(BaseModel):
+    active_provider: str = "gemini"  # gemini | codex | openai_compatible | anthropic
+    theme: str = "graphite"
+    default_ai_apply_mode: str = "replace_cell"  # replace_cell | append_cell
+    include_kernel_variables: bool = True
+    providers: dict[str, ProviderSettings] = Field(
+        default_factory=lambda: {
+            "gemini": ProviderSettings(
+                api_key="",
+                model="gemini-2.5-flash",
+                base_url="https://generativelanguage.googleapis.com/v1beta",
+            ),
+            "codex": ProviderSettings(
+                api_key="",
+                model="",
+                base_url="",
+                reasoning_effort="low",
+            ),
+            "openai_compatible": ProviderSettings(
+                api_key="",
+                model="gpt-4.1-mini",
+                base_url="https://api.openai.com/v1",
+            ),
+            "anthropic": ProviderSettings(
+                api_key="",
+                model="claude-sonnet-4-5",
+                base_url="https://api.anthropic.com/v1",
+            ),
+        }
+    )
+
+
+class ConfigManager:
+    def __init__(self) -> None:
+        self._migrate_legacy_if_needed()
+        self._config = self._load()
+        self._workspace_path = self._resolve_initial_workspace()
+
+    def _migrate_legacy_if_needed(self) -> None:
+        if not CONFIG_FILE.exists() and LEGACY_CONFIG_FILE.exists():
+            try:
+                CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(LEGACY_CONFIG_FILE, CONFIG_FILE)
+            except Exception:
+                pass
+
+    def _resolve_initial_workspace(self) -> Path:
+        env_ws = (
+            os.environ.get("SATURNOLAB_WORKSPACE", "").strip()
+            or os.environ.get("SATURNO_WORKSPACE", "").strip()
+        )
+        if env_ws:
+            target = Path(env_ws).expanduser().resolve()
+            target.mkdir(parents=True, exist_ok=True)
+            return target
+        return Path.cwd().resolve()
+
+    def _load(self) -> SaturnoConfig:
+        cfg = SaturnoConfig()
+        if CONFIG_FILE.exists():
+            try:
+                raw = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+                # Ignore deprecated workspace_dir key from older configs
+                raw.pop("workspace_dir", None)
+                loaded = SaturnoConfig.model_validate(raw)
+                for key, default_val in cfg.providers.items():
+                    if key not in loaded.providers:
+                        loaded.providers[key] = default_val
+                cfg = loaded
+            except Exception:
+                pass
+        return cfg
+
+    def save(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        CONFIG_FILE.write_text(
+            json.dumps(self._config.model_dump(), indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+
+    @property
+    def config(self) -> SaturnoConfig:
+        return self._config
+
+    def get_workspace_path(self) -> Path:
+        if not self._workspace_path.exists():
+            self._workspace_path.mkdir(parents=True, exist_ok=True)
+        return self._workspace_path
+
+    def set_workspace_path(self, new_dir: str) -> Path:
+        target = Path(new_dir).expanduser().resolve()
+        if not target.exists() or not target.is_dir():
+            raise ValueError(f"Diretório não encontrado: {new_dir}")
+        self._workspace_path = target
+        return target
+
+    def update_settings(self, patch: dict[str, Any]) -> SaturnoConfig:
+        if "active_provider" in patch and patch["active_provider"]:
+            self._config.active_provider = str(patch["active_provider"])
+        if "theme" in patch and patch["theme"] in VALID_THEMES:
+            self._config.theme = str(patch["theme"])
+        if "default_ai_apply_mode" in patch and patch["default_ai_apply_mode"] in (
+            "replace_cell",
+            "append_cell",
+        ):
+            self._config.default_ai_apply_mode = patch["default_ai_apply_mode"]
+        if "include_kernel_variables" in patch:
+            self._config.include_kernel_variables = bool(patch["include_kernel_variables"])
+        if "providers" in patch and isinstance(patch["providers"], dict):
+            for prov_name, prov_data in patch["providers"].items():
+                if not isinstance(prov_data, dict):
+                    continue
+                existing = self._config.providers.get(prov_name, ProviderSettings())
+                updated_dict = existing.model_dump()
+                for k, v in prov_data.items():
+                    if k == "api_key" and v == "********":
+                        continue
+                    if k in updated_dict and v is not None:
+                        updated_dict[k] = v
+                self._config.providers[prov_name] = ProviderSettings(**updated_dict)
+        self.save()
+        return self._config
+
+    def resolve_api_key(self, provider: str) -> str:
+        prov = self._config.providers.get(provider)
+        if prov and prov.api_key.strip():
+            return prov.api_key.strip()
+        env_map = {
+            "gemini": ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+            "codex": ["CODEX_API_KEY", "OPENAI_API_KEY"],
+            "openai_compatible": ["OPENAI_API_KEY"],
+            "anthropic": ["ANTHROPIC_API_KEY"],
+        }
+        for env_name in env_map.get(provider, []):
+            val = os.environ.get(env_name, "").strip()
+            if val:
+                return val
+        return ""
+
+    @staticmethod
+    def resolve_codex_binary() -> str | None:
+        found = shutil.which("codex")
+        if found:
+            return found
+        local_bin = Path.home() / ".local" / "bin" / "codex"
+        if local_bin.exists():
+            return str(local_bin)
+        return None
+
+    def public_dict(self) -> dict[str, Any]:
+        data = self._config.model_dump()
+        codex_bin = self.resolve_codex_binary()
+        npx_bin = shutil.which("npx")
+        codex_auth_exists = (Path.home() / ".codex" / "auth.json").exists()
+
+        providers_out: dict[str, Any] = {}
+        for name, p in data["providers"].items():
+            resolved_key = self.resolve_api_key(name)
+            providers_out[name] = {
+                **p,
+                "api_key": "********" if p.get("api_key") else "",
+                "has_key": bool(resolved_key),
+            }
+        return {
+            **data,
+            "workspace_dir": str(self.get_workspace_path()),
+            "providers": providers_out,
+            "codex_status": {
+                "cli_installed": bool(codex_bin),
+                "auth_found": codex_auth_exists,
+                "sdk_ready": bool(codex_bin or npx_bin),
+            },
+        }
+
+
+config_manager = ConfigManager()