baldanders 0.1.0__py3-none-any.whl

baldanders/__init__.py

@@ -0,0 +1,3 @@
+"""Baldanders — local personal-data firewall for cloud LLMs."""
+
+__version__ = "0.1.0"

baldanders/cli.py

@@ -0,0 +1,365 @@
+"""Baldanders CLI — personal-data firewall for cloud LLMs."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+
+import click
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.progress import BarColumn, DownloadColumn, Progress, TextColumn, TransferSpeedColumn
+from rich.text import Text
+
+from baldanders import __version__
+from baldanders.config import Config, create_default_config, load_config
+from baldanders.history import (
+    delete_session, list_sessions, load_session, new_session_id, save_session,
+)
+from baldanders.mapping import SessionMap
+from baldanders.model_manager import download_model, is_downloaded, model_dir
+from baldanders.providers.base import BaseProvider
+from baldanders.scrubber.engine import ScrubEngine
+
+console = Console(highlight=False)
+
+PROVIDERS = ["claude", "chatgpt", "grok", "anthropic-api", "openai-api", "deepseek", "groq"]
+
+_OPENAI_COMPATIBLE = {
+    # name: (base url, default model, api key env var)
+    "openai-api": ("https://api.openai.com/v1", "gpt-4o", "OPENAI_API_KEY"),
+    "deepseek": ("https://api.deepseek.com/v1", "deepseek-chat", "DEEPSEEK_API_KEY"),
+    "groq": ("https://api.groq.com/openai/v1", "llama-3.3-70b-versatile", "GROQ_API_KEY"),
+}
+
+HELP_TEXT = (
+    "/paste  multi-line input (end with a single . on its own line)\n"
+    "/map    show which token stands for which real value\n"
+    "/raw    toggle scrubbing off/on for the next messages\n"
+    "/clear  start a fresh conversation (keeps the token map)\n"
+    "/help   show this help\n"
+    "/quit   exit"
+)
+
+
+def _build_provider(name: str, api_key: str | None, base_url: str | None) -> BaseProvider:
+    # Consumer-auth providers (no API key needed)
+    if name == "claude":
+        from baldanders.providers.claude_code import ClaudeCodeProvider
+        return ClaudeCodeProvider()
+    if name == "chatgpt":
+        from baldanders.providers.codex import CodexProvider
+        return CodexProvider()
+    if name == "grok":
+        from baldanders.providers.grok import GrokCLIProvider
+        return GrokCLIProvider()
+
+    # API-key providers
+    if name == "anthropic-api":
+        from baldanders.providers.anthropic import AnthropicProvider
+        return AnthropicProvider(api_key=api_key)
+    if name in _OPENAI_COMPATIBLE:
+        from baldanders.providers.openai import OpenAIProvider
+        url, model, key_env = _OPENAI_COMPATIBLE[name]
+        provider = OpenAIProvider(api_key=api_key, base_url=base_url or url, default_model=model, key_env=key_env)
+        provider.name = name
+        return provider
+    raise click.BadParameter(f"Unknown provider: {name}")
+
+
+def _build_engine(session_map: SessionMap, config: Config) -> ScrubEngine:
+    md = model_dir() if is_downloaded() else None
+    engine = ScrubEngine(session_map, model_dir=md, config=config)
+    for problem in engine.config_errors:
+        console.print(f"[yellow]Config:[/yellow] {problem}")
+    return engine
+
+
+def _read_input(raw_mode: bool) -> str | None:
+    """Read one message from the terminal. Returns None on EOF/Ctrl-C."""
+    prompt = "[bold red]Raw:[/bold red] " if raw_mode else "[bold blue]You:[/bold blue] "
+    try:
+        first_line = console.input(prompt)
+    except (EOFError, KeyboardInterrupt):
+        return None
+
+    if first_line.strip().lower() == "/paste":
+        console.print("[dim]  Paste your text. Type a single . on a line to send.[/dim]")
+        lines: list[str] = []
+        while True:
+            try:
+                line = console.input("[dim]...:[/dim] ")
+            except (EOFError, KeyboardInterrupt):
+                break
+            if line.strip() == ".":
+                break
+            lines.append(line)
+        return "\n".join(lines).strip()
+
+    lines = [first_line]
+    if first_line.rstrip().endswith(("(", "{", "[", ",", "\\", ";")):
+        console.print("[dim]  (multi-line: empty line to send)[/dim]")
+        while True:
+            try:
+                line = console.input("[dim]...:[/dim] ")
+            except (EOFError, KeyboardInterrupt):
+                break
+            if line.strip() == "":
+                break
+            lines.append(line)
+    return "\n".join(lines).strip()
+
+
+async def _repl(
+    provider: BaseProvider,
+    engine: ScrubEngine,
+    session_map: SessionMap,
+    messages: list[dict[str, str]],
+    session_id: str,
+    model: str | None,
+    verbose: bool = False,
+    save: bool = True,
+) -> None:
+    ner = engine.ner_status
+    ner_line = "[green]loaded[/green]" if ner == "loaded" else f"[yellow]regex-only[/yellow] [dim]({ner})[/dim]"
+    console.print()
+    console.print(Panel(
+        f"[bold]Baldanders {__version__}[/bold] — your personal data never leaves this machine.\n"
+        f"Provider: [bold]{provider.name}[/bold]   Session: [dim]{session_id}{'' if save else ' (not saved)'}[/dim]\n"
+        f"Name/address model: {ner_line}\n"
+        "Commands: [dim]/paste  /map  /raw  /clear  /help  /quit[/dim]",
+        border_style="blue",
+    ))
+    console.print()
+
+    raw_mode = False
+
+    def persist() -> None:
+        if save:
+            save_session(session_id, session_map, messages, provider_state=provider.get_state())
+
+    while True:
+        raw = _read_input(raw_mode)
+        if raw is None:
+            console.print("\n[dim]Bye.[/dim]")
+            break
+        if not raw:
+            continue
+
+        command = raw.lower()
+        if command in ("/quit", "/exit"):
+            console.print("[dim]Bye.[/dim]")
+            break
+        if command == "/help":
+            console.print(Text(HELP_TEXT, style="dim"))
+            console.print()
+            continue
+        if command == "/map":
+            mapping = session_map.get_map()
+            if not mapping:
+                console.print("[dim]No personal data mapped yet.[/dim]")
+            for token, real in mapping.items():
+                line = Text("  ")
+                line.append(token)
+                line.append(" → ")
+                line.append(real, style="bold")
+                console.print(line)
+            console.print()
+            continue
+        if command == "/raw":
+            raw_mode = not raw_mode
+            if raw_mode:
+                console.print("[bold red]Raw mode ON — messages are sent exactly as typed, with no scrubbing.[/bold red]\n")
+            else:
+                console.print("[dim]Raw mode OFF — scrubbing enabled.[/dim]\n")
+            continue
+        if command == "/clear":
+            messages.clear()
+            provider.reset()
+            persist()
+            console.print("[dim]Conversation cleared.[/dim]\n")
+            continue
+
+        # Scrub personal data (unless raw mode)
+        if raw_mode:
+            scrubbed = raw
+        else:
+            scrubbed = engine.scrub(raw)
+            if scrubbed != raw:
+                diff = Text("  [scrubbed] ", style="dim yellow")
+                diff.append(scrubbed, style="yellow")
+                console.print(diff)
+
+        if verbose:
+            console.print()
+            console.print(Panel(
+                Text(scrubbed),
+                title="[bold red]SENT TO AI (exactly this, nothing else)[/bold red]",
+                border_style="red",
+            ))
+            console.print()
+
+        messages.append({"role": "user", "content": scrubbed})
+
+        try:
+            with console.status("[dim]Thinking...[/dim]"):
+                response = await provider.send(messages, model=model)
+        except KeyboardInterrupt:
+            console.print("[dim]Cancelled.[/dim]\n")
+            messages.pop()
+            continue
+        except Exception as e:
+            console.print(Text.assemble(("Error: ", "red"), str(e)))
+            console.print()
+            messages.pop()
+            continue
+
+        if verbose:
+            console.print(Panel(
+                Text(response),
+                title="[bold cyan]RAW RESPONSE FROM AI[/bold cyan]",
+                border_style="cyan",
+            ))
+
+        messages.append({"role": "assistant", "content": response})
+
+        # Restore personal data in the response
+        rehydrated = session_map.rehydrate(response)
+
+        console.print()
+        console.print("[bold green]Assistant:[/bold green]")
+        console.print(Markdown(rehydrated))
+        console.print()
+
+        persist()
+
+
+@click.group(invoke_without_command=True)
+@click.option("--provider", "-p", default="claude", type=click.Choice(PROVIDERS),
+              help="LLM backend. claude/chatgpt/grok use your subscription (no API key).")
+@click.option("--model", "-m", default=None, help="Model name override.")
+@click.option("--api-key", default=None, envvar="BALDANDERS_API_KEY",
+              help="API key (only needed for direct API providers).")
+@click.option("--base-url", default=None, help="Custom API base URL (OpenAI-compatible providers).")
+@click.option("--verbose", "-v", is_flag=True, help="Show exact text sent to and received from AI.")
+@click.option("--resume", "-r", default=None, help="Resume a previous session by ID.")
+@click.option("--no-save", is_flag=True, help="Don't write this session to disk.")
+@click.version_option(__version__, prog_name="baldanders")
+@click.pass_context
+def main(ctx: click.Context, provider: str, model: str | None, api_key: str | None,
+         base_url: str | None, verbose: bool, resume: str | None, no_save: bool) -> None:
+    """Baldanders — local personal-data firewall for cloud LLMs."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    try:
+        llm = _build_provider(provider, api_key, base_url)
+    except (ValueError, RuntimeError, click.BadParameter) as e:
+        console.print(Text(str(e), style="red"))
+        sys.exit(1)
+
+    create_default_config()
+    config = load_config()
+    save = config.save_sessions and not no_save
+
+    if resume:
+        loaded = load_session(resume)
+        if not loaded:
+            console.print(Text(f"Session '{resume}' not found.", style="red"))
+            sys.exit(1)
+        session_map, messages, provider_state = loaded
+        llm.set_state(provider_state)
+        session_id = resume
+        console.print(f"[dim]Resumed session {session_id} ({len(messages)} messages)[/dim]")
+    else:
+        session_map = SessionMap()
+        messages = []
+        session_id = new_session_id()
+
+    engine = _build_engine(session_map, config)
+
+    async def run() -> None:
+        try:
+            await _repl(llm, engine, session_map, messages, session_id, model, verbose=verbose, save=save)
+        finally:
+            if save and messages:
+                save_session(session_id, session_map, messages, provider_state=llm.get_state())
+            await llm.aclose()
+
+    asyncio.run(run())
+
+
+@main.command()
+def download() -> None:
+    """Download the multilingual name-and-address model (~320 MB)."""
+    try:
+        import gliner  # noqa: F401
+    except ImportError:
+        console.print('[yellow]Note:[/yellow] the model needs the NER extra: pip install "baldanders[ner]"')
+
+    with Progress(
+        TextColumn("[dim]{task.description}"), BarColumn(), DownloadColumn(), TransferSpeedColumn(),
+        console=console,
+    ) as progress:
+        tasks: dict[str, int] = {}
+
+        def on_progress(name: str, done: int, total: int | None) -> None:
+            if name not in tasks:
+                tasks[name] = progress.add_task(name, total=total)
+            progress.update(tasks[name], completed=done)
+
+        try:
+            path = asyncio.run(download_model(progress=on_progress))
+        except Exception as e:
+            console.print(Text(f"Download failed: {e}", style="red"))
+            sys.exit(1)
+    console.print(f"[green]Model ready in {path}[/green]")
+
+
+@main.command()
+@click.argument("text", required=False)
+@click.option("--show-map", is_flag=True, help="Also print the token → value mapping (to stderr).")
+@click.option("--json", "as_json", is_flag=True, help="Print detected spans as JSON instead.")
+def scrub(text: str | None, show_map: bool, as_json: bool) -> None:
+    """Scrub TEXT (or stdin) and print the result. Nothing is sent anywhere."""
+    if text is None:
+        text = sys.stdin.read()
+    session_map = SessionMap()
+    engine = _build_engine(session_map, load_config())
+    if as_json:
+        spans = engine.detect(text)
+        click.echo(json.dumps(
+            [{"start": s.start, "end": s.end, "type": s.entity_type, "text": s.text} for s in spans],
+            ensure_ascii=False, indent=2,
+        ))
+        return
+    click.echo(engine.scrub(text), nl=not text.endswith("\n"))
+    if show_map:
+        for token, real in session_map.get_map().items():
+            click.echo(f"{token} → {real}", err=True)
+
+
+@main.command()
+@click.option("--delete", "delete_id", default=None, metavar="ID", help="Delete a saved session.")
+def sessions(delete_id: str | None) -> None:
+    """List saved sessions."""
+    if delete_id:
+        if delete_session(delete_id):
+            console.print(f"[dim]Deleted session {delete_id}.[/dim]")
+        else:
+            console.print(Text(f"Session '{delete_id}' not found.", style="red"))
+        return
+    saved = list_sessions()
+    if not saved:
+        console.print("[dim]No saved sessions.[/dim]")
+        return
+    for s in saved:
+        provider = f"  {s['provider']}" if s.get("provider") else ""
+        console.print(f"  [bold]{s['id']}[/bold]  {s['message_count']} messages{provider}  [dim]{s['updated_at']}[/dim]")
+    console.print("\n[dim]Resume with: baldanders --resume <id>[/dim]")
+
+
+if __name__ == "__main__":
+    main()

baldanders/config.py

@@ -0,0 +1,133 @@
+"""User configuration — allowlist, denylist, custom patterns, regions."""
+
+from __future__ import annotations
+
+import locale
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+BASE_DIR = Path(os.environ.get("BALDANDERS_HOME", Path.home() / ".baldanders"))
+DEFAULT_CONFIG_PATH = BASE_DIR / "config.yaml"
+
+
+@dataclass
+class Config:
+    # Terms that should NEVER be scrubbed (S3 buckets, table names, etc.)
+    allowlist: list[str] = field(default_factory=list)
+
+    # Terms that should ALWAYS be scrubbed (custom sensitive values)
+    denylist: dict[str, str] = field(default_factory=dict)  # value -> entity_type
+
+    # Extra regex patterns: entity name -> pattern string
+    custom_patterns: dict[str, str] = field(default_factory=dict)
+
+    # Countries (ISO 3166 alpha-2) whose local phone formats to recognise.
+    # Numbers written with a +country prefix are always recognised.
+    regions: list[str] = field(default_factory=list)
+
+    # Also scrub checksum-valid ID numbers that have no keyword ("DNI", "BSN", ...) nearby.
+    paranoid: bool = False
+
+    # NER confidence threshold (0-1) for all entity types. None = tuned per-type defaults.
+    ner_threshold: float | None = None
+
+    # Write conversations and the token mapping to ~/.baldanders/sessions.
+    save_sessions: bool = True
+
+
+def system_regions() -> list[str]:
+    """Best guess at the user's country from the OS locale (e.g. es_AR -> AR)."""
+    candidates = [os.environ.get(v, "") for v in ("LC_ALL", "LC_TELEPHONE", "LANG")]
+    try:
+        candidates.append(locale.getlocale()[0] or "")
+    except Exception:
+        pass
+    for value in candidates:
+        m = re.match(r"^[a-z]{2,3}[_-]([A-Z]{2})\b", value)
+        if m:
+            return [m.group(1)]
+    return []
+
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH) -> Config:
+    """Load config from YAML file. Returns defaults if file doesn't exist."""
+    if not path.exists():
+        return Config(regions=system_regions())
+
+    try:
+        import yaml
+    except ImportError:
+        log.warning("PyYAML not installed — ignoring config file. pip install pyyaml")
+        return Config(regions=system_regions())
+
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except Exception:
+        log.warning("Failed to parse config at %s", path, exc_info=True)
+        return Config(regions=system_regions())
+
+    regions = [str(r).upper() for r in (data.get("regions") or [])] or system_regions()
+    return Config(
+        allowlist=[str(t) for t in (data.get("allowlist") or [])],
+        denylist={str(k): str(v).upper() for k, v in (data.get("denylist") or {}).items()},
+        custom_patterns={str(k): str(v) for k, v in (data.get("custom_patterns") or {}).items()},
+        regions=regions,
+        paranoid=bool(data.get("paranoid", False)),
+        ner_threshold=float(data["ner_threshold"]) if data.get("ner_threshold") is not None else None,
+        save_sessions=bool(data.get("save_sessions", True)),
+    )
+
+
+def create_default_config(path: Path = DEFAULT_CONFIG_PATH) -> None:
+    """Create a starter config file with examples."""
+    if path.exists():
+        return
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("""\
+# Baldanders configuration
+# ========================
+
+# Countries whose local phone formats to recognise (ISO codes like AR, US, DE, IN).
+# Numbers with a +country prefix are always caught. Empty = guess from your OS locale.
+regions: []
+  # - AR
+  # - US
+
+# Also scrub checksum-valid ID numbers (BSN, PESEL, Steuer-ID, ...) even when
+# no keyword like "DNI" or "BSN" is nearby. Catches more, but plain numbers
+# in code or maths may get tokenised too.
+paranoid: false
+
+# Name/address model confidence (0-1). Lower catches more, with more false
+# positives. Leave unset for tuned defaults (names 0.7, addresses 0.4).
+# ner_threshold: 0.6
+
+# Save conversations (including the real values behind each token) to
+# ~/.baldanders/sessions so you can --resume them. Files are readable only by you.
+save_sessions: true
+
+# Terms that should NEVER be scrubbed.
+# Use this for internal infrastructure names, bucket names, table names, etc.
+allowlist:
+  # - verify-internal-data-prod
+  # - my-s3-bucket-name
+
+# Terms that should ALWAYS be scrubbed (case-insensitive), mapped to an entity type.
+# Use this for values the detectors might miss.
+denylist: {}
+  # "Acme Corp Internal": ORGANIZATION
+  # "Project Falcon": PROJECT
+
+# Custom regex patterns. The whole match is scrubbed; if the pattern has a
+# capturing group, only the first group is.
+custom_patterns: {}
+  # customer_id: "CID-\\\\d{8}"
+  # portfolio_ref: "PF/\\\\d{4}/\\\\d{6}"
+""", encoding="utf-8")
+    log.info("Created default config at %s", path)

baldanders/history.py

@@ -0,0 +1,127 @@
+"""Session history — persists token mapping and conversation across restarts.
+
+Session files contain the real values behind every token, so they are written
+atomically with owner-only permissions (0600, directory 0700).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from baldanders.config import BASE_DIR
+from baldanders.mapping import SessionMap
+
+log = logging.getLogger(__name__)
+
+DEFAULT_HISTORY_DIR = BASE_DIR / "sessions"
+
+_SESSION_ID = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+def _session_path(session_id: str, history_dir: Path = DEFAULT_HISTORY_DIR) -> Path:
+    if not _SESSION_ID.match(session_id):
+        raise ValueError(f"Invalid session id: {session_id!r}")
+    return history_dir / f"{session_id}.json"
+
+
+def _ensure_private_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path, 0o700)
+    except OSError:
+        pass
+
+
+def save_session(
+    session_id: str,
+    session_map: SessionMap,
+    messages: list[dict[str, str]],
+    history_dir: Path = DEFAULT_HISTORY_DIR,
+    provider_state: dict[str, Any] | None = None,
+) -> None:
+    """Save session state to disk."""
+    _ensure_private_dir(history_dir)
+    path = _session_path(session_id, history_dir)
+    data = {
+        "session_id": session_id,
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "mapping": session_map.to_dict(),
+        "messages": messages,
+        "provider_state": provider_state or {},
+    }
+    # mkstemp creates the file with 0600 permissions.
+    fd, tmp = tempfile.mkstemp(dir=history_dir, prefix=".tmp-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+    log.debug("Session saved to %s", path)
+
+
+def load_session(
+    session_id: str,
+    history_dir: Path = DEFAULT_HISTORY_DIR,
+) -> tuple[SessionMap, list[dict[str, str]], dict[str, Any]] | None:
+    """Load a saved session. Returns (session_map, messages, provider_state) or None."""
+    try:
+        path = _session_path(session_id, history_dir)
+    except ValueError:
+        return None
+    if not path.exists():
+        return None
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+        log.warning("Failed to load session %s", session_id)
+        return None
+
+    session_map = SessionMap.from_dict(data.get("mapping", {}))
+    messages = data.get("messages", [])
+    return session_map, messages, data.get("provider_state") or {}
+
+
+def list_sessions(history_dir: Path = DEFAULT_HISTORY_DIR) -> list[dict]:
+    """List all saved sessions."""
+    if not history_dir.exists():
+        return []
+
+    sessions = []
+    for path in sorted(history_dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            sessions.append({
+                "id": data.get("session_id", path.stem),
+                "updated_at": data.get("updated_at", ""),
+                "message_count": len(data.get("messages", [])),
+                "provider": (data.get("provider_state") or {}).get("provider", ""),
+            })
+        except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+            continue
+    return sessions
+
+
+def delete_session(session_id: str, history_dir: Path = DEFAULT_HISTORY_DIR) -> bool:
+    try:
+        path = _session_path(session_id, history_dir)
+    except ValueError:
+        return False
+    if path.exists():
+        path.unlink()
+        return True
+    return False
+
+
+def new_session_id() -> str:
+    """Generate a session ID from the current timestamp."""
+    return datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")