aida-workbench 0.0.1__py3-none-any.whl

aida/__init__.py

@@ -0,0 +1,7 @@
+"""AIDA — AI Data Assistant.
+
+A local scientific agent workbench. See PLAN.md at the repository root for
+the full design and phase map.
+"""
+
+__version__ = "0.0.1"

aida/artifacts/__init__.py

@@ -0,0 +1 @@
+"""Typed tool-result artifacts (image, file, table) and the artifact store. Never imports Qt. Filled in starting Phase 3."""

aida/cli/__init__.py

@@ -0,0 +1,6 @@
+"""AIDA command-line interface.
+
+Phase 1 ships only ``aida doctor``. ``chat.py`` (Phase 2), ``run.py``
+(Phase 10), and ``config_cmds.py`` are placeholders that later phases fill
+in — see PLAN.md §10.
+"""

aida/cli/__main__.py

@@ -0,0 +1,61 @@
+"""Entry point for the ``aida`` console script (and ``aida-gui`` stub)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from aida.config.logging_setup import configure_logging
+from aida.config.settings import load_settings
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="aida", description="AIDA — AI Data Assistant")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("doctor", help="Report environment/config diagnostics")
+    sub.add_parser("chat", help="Interactive chat (Phase 2)")
+    sub.add_parser("run", help="Run a stored workflow headlessly (Phase 10)")
+    sub.add_parser("config", help="Show on-device config locations")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    settings = load_settings()
+    configure_logging(settings.app.log_level)
+
+    if args.command == "doctor":
+        from aida.cli.doctor import main as doctor_main
+
+        return doctor_main()
+    if args.command == "chat":
+        from aida.cli.chat import main as chat_main
+
+        return chat_main()
+    if args.command == "run":
+        from aida.cli.run import main as run_main
+
+        return run_main()
+    if args.command == "config":
+        from aida.cli.config_cmds import main as config_main
+
+        return config_main()
+
+    parser.print_help()
+    return 0
+
+
+def main_gui() -> int:
+    """Stub for the ``aida-gui`` entry point; the real GUI arrives in Phase 5."""
+    print("aida-gui: not yet implemented (arrives in Phase 5 — see PLAN.md §10).")
+    print("Use `aida doctor` or `aida chat` (Phase 2) for now.")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aida/cli/chat.py

@@ -0,0 +1,12 @@
+"""``aida chat`` — interactive streaming chat with a provider.
+
+Placeholder: implemented in Phase 2 (provider layer + agent loop). Present
+here only so the repository structure in PLAN.md §3 exists from Phase 1.
+"""
+
+from __future__ import annotations
+
+
+def main(_argv: list[str] | None = None) -> int:
+    print("aida chat: not yet implemented (arrives in Phase 2 — see PLAN.md §10).")
+    return 1

aida/cli/config_cmds.py

@@ -0,0 +1,16 @@
+"""``aida config`` — inspect/edit on-device configuration.
+
+Phase 1 provides just enough to show where things live; richer editing
+(profile add/remove, workspace edit, etc.) arrives alongside the phases that
+give those concepts real behavior (Phase 2 providers, Phase 4 workspaces).
+"""
+
+from __future__ import annotations
+
+from aida.config.paths import app_dir, ensure_records_dir
+
+
+def main(_argv: list[str] | None = None) -> int:
+    print(f"AIDA config directory: {app_dir()}")
+    print(f"AIDA records directory: {ensure_records_dir()}")
+    return 0

aida/cli/doctor.py

@@ -0,0 +1,153 @@
+"""``aida doctor`` — environment and configuration diagnostics.
+
+Reports, per PLAN.md Phase 1 acceptance criteria:
+
+- Python version
+- config file status/validity (config.yaml, providers.yaml, workspaces.yaml,
+  mcp.json)
+- keyring availability
+- reachable provider endpoints (ping only — Phase 1 has no provider layer
+  yet, so this is a placeholder that reports "not configured" rather than
+  failing)
+- writable dirs (``~/.aida`` and its subdirectories, records dir)
+
+Designed to be used both as a CLI command and importable for tests: the
+report is built as a list of ``CheckResult`` and formatting is separate from
+checking, so tests can assert on structured results without parsing text.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from aida.config import paths
+from aida.config.secrets import keyring_available
+from aida.config.settings import Settings, load_settings
+
+
+@dataclass
+class CheckResult:
+    name: str
+    ok: bool
+    detail: str
+
+
+def _check_python_version() -> CheckResult:
+    major, minor = sys.version_info[:2]
+    ok = (major, minor) >= (3, 11)
+    return CheckResult(
+        "python_version",
+        ok,
+        f"Python {sys.version.split()[0]}" + ("" if ok else " (need >= 3.11)"),
+    )
+
+
+def _check_writable(name: str, path: Path) -> CheckResult:
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        probe = path / ".aida_write_test"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        return CheckResult(name, True, f"writable: {path}")
+    except OSError as exc:
+        return CheckResult(name, False, f"NOT writable: {path} ({exc})")
+
+
+def _load_settings_safely() -> tuple[Settings | None, CheckResult]:
+    """Load settings once, turning a bad config into a failed check instead
+    of an exception — every other check that needs settings reuses this
+    result rather than calling ``load_settings()`` again unguarded."""
+    try:
+        settings = load_settings()
+        return settings, CheckResult(
+            "config_files",
+            True,
+            "config.yaml, providers.yaml, workspaces.yaml, mcp.json loaded "
+            f"(config_version={settings.app.config_version})",
+        )
+    except Exception as exc:  # noqa: BLE001 - doctor must never crash on bad config
+        return None, CheckResult("config_files", False, f"failed to load: {exc}")
+
+
+def _check_keyring() -> CheckResult:
+    ok = keyring_available()
+    return CheckResult(
+        "keyring",
+        ok,
+        "keyring backend available" if ok else "no usable keyring backend found",
+    )
+
+
+def _check_provider_endpoints(settings: Settings | None) -> list[CheckResult]:
+    """Ping-only checks for configured provider profiles.
+
+    Phase 1 ships no provider layer, so with zero profiles configured this
+    reports an informational pass rather than a failure — providers arrive
+    in Phase 2. If settings failed to load at all, that is already reported
+    by the ``config_files`` check, so this is skipped rather than duplicated.
+    """
+    if settings is None:
+        return []
+
+    profiles = settings.providers.profiles
+    if not profiles:
+        return [
+            CheckResult(
+                "provider_endpoints",
+                True,
+                "no provider profiles configured yet (expected before Phase 2)",
+            )
+        ]
+
+    results: list[CheckResult] = []
+    for name, profile in profiles.items():
+        # Ping-only, best-effort: Phase 1 does not depend on network access,
+        # so a failed/absent connection is reported, not raised.
+        try:
+            import urllib.request
+
+            if not profile.base_url:
+                results.append(
+                    CheckResult(f"provider:{name}", True, "no base_url set (SDK default)")
+                )
+                continue
+            req = urllib.request.Request(profile.base_url, method="HEAD")
+            urllib.request.urlopen(req, timeout=2)  # noqa: S310
+            results.append(CheckResult(f"provider:{name}", True, f"reachable: {profile.base_url}"))
+        except Exception as exc:  # noqa: BLE001
+            results.append(
+                CheckResult(f"provider:{name}", False, f"unreachable: {profile.base_url} ({exc})")
+            )
+    return results
+
+
+def run_checks() -> list[CheckResult]:
+    results: list[CheckResult] = [_check_python_version()]
+    settings, config_result = _load_settings_safely()
+    results.append(config_result)
+    results.append(_check_writable("app_dir", paths.app_dir()))
+    results.append(_check_writable("logs_dir", paths.logs_dir()))
+    results.append(_check_writable("artifacts_dir", paths.artifacts_dir()))
+    results.append(_check_writable("records_dir", paths.ensure_records_dir()))
+    results.append(_check_keyring())
+    results.extend(_check_provider_endpoints(settings))
+    return results
+
+
+def format_report(results: list[CheckResult]) -> str:
+    lines = ["AIDA doctor report", "=" * 19]
+    for r in results:
+        mark = "OK  " if r.ok else "FAIL"
+        lines.append(f"[{mark}] {r.name}: {r.detail}")
+    n_fail = sum(1 for r in results if not r.ok)
+    lines.append("")
+    lines.append(f"{len(results) - n_fail}/{len(results)} checks passed.")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    results = run_checks()
+    print(format_report(results))
+    return 1 if any(not r.ok for r in results) else 0

aida/cli/run.py

@@ -0,0 +1,12 @@
+"""``aida run`` — headless execution of stored named workflows.
+
+Placeholder: implemented in Phase 10. Present here only so the repository
+structure in PLAN.md §3 exists from Phase 1.
+"""
+
+from __future__ import annotations
+
+
+def main(_argv: list[str] | None = None) -> int:
+    print("aida run: not yet implemented (arrives in Phase 10 — see PLAN.md §10).")
+    return 1

aida/coding/__init__.py

@@ -0,0 +1 @@
+"""Small-scale coding support: templates, sandboxed script execution. Never imports Qt. Filled in starting Phase 9."""

aida/config/__init__.py

@@ -0,0 +1,4 @@
+"""Configuration subsystem: on-device paths, settings, and secrets.
+
+Nothing in this package may import Qt (see PLAN.md §3, layering rules).
+"""

aida/config/logging_setup.py

@@ -0,0 +1,64 @@
+"""Logging configuration: rotating file log + console handler.
+
+Groundwork for "which layer failed" diagnostics (PLAN.md §7, §11): every
+logger name is namespaced by subsystem (``aida.provider``, ``aida.mcp``,
+``aida.core``, ``aida.ui``, ...) and the formatter includes that name, so a
+log line always identifies which layer produced it.
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+from pathlib import Path
+
+from aida.config.paths import logs_dir
+
+LOG_FORMAT = "%(asctime)s %(levelname)-8s %(name)s: %(message)s"
+LOG_FILENAME = "aida.log"
+MAX_BYTES = 5 * 1024 * 1024
+BACKUP_COUNT = 5
+
+_configured = False
+
+
+def configure_logging(level: str = "INFO", *, log_dir: Path | None = None) -> Path:
+    """Configure the ``aida`` logger tree once per process.
+
+    Safe to call more than once (e.g. once from config defaults, once after
+    the user's real config loads with a different level) — later calls just
+    adjust the level rather than duplicating handlers.
+    """
+    global _configured
+
+    root = logging.getLogger("aida")
+    root.setLevel(level.upper())
+
+    target_dir = log_dir or logs_dir()
+    log_path = target_dir / LOG_FILENAME
+
+    if not _configured:
+        formatter = logging.Formatter(LOG_FORMAT)
+
+        file_handler = logging.handlers.RotatingFileHandler(
+            log_path, maxBytes=MAX_BYTES, backupCount=BACKUP_COUNT, encoding="utf-8"
+        )
+        file_handler.setFormatter(formatter)
+        root.addHandler(file_handler)
+
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(formatter)
+        root.addHandler(console_handler)
+
+        _configured = True
+
+    return log_path
+
+
+def get_logger(subsystem: str) -> logging.Logger:
+    """Return a logger namespaced under ``aida.<subsystem>``.
+
+    ``subsystem`` should be one of the recognized layer tags: ``provider``,
+    ``mcp``, ``core``, ``ui``, ``config``, ``cli``, ``workspace``, ``docs``.
+    """
+    return logging.getLogger(f"aida.{subsystem}")

aida/config/paths.py

@@ -0,0 +1,90 @@
+"""Resolve and create AIDA's on-device directories.
+
+Two roots (PLAN.md §4):
+
+- ``~/.aida/`` — app state: config files, secrets refs, the SQLite DB,
+  binary artifacts, and logs. Never inside a repo; never contains secrets.
+- ``~/Documents/Aida/`` (configurable via ``config.yaml``'s ``records_dir``)
+  — human-readable conversation records / exported transcripts. Safe to
+  browse, safe to delete.
+
+Every function here is idempotent: calling it repeatedly, or on first run
+with nothing on disk yet, must succeed and create what's missing.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+APP_DIR_ENV_VAR = "AIDA_HOME"
+DEFAULT_RECORDS_DIRNAME = "Aida"
+
+
+def app_dir() -> Path:
+    """Return ``~/.aida/`` (or ``$AIDA_HOME`` if set), creating it if needed.
+
+    ``AIDA_HOME`` override exists for tests and for headless/CI use so tests
+    never touch a developer's real ``~/.aida``.
+    """
+    override = os.environ.get(APP_DIR_ENV_VAR)
+    base = Path(override).expanduser() if override else Path.home() / ".aida"
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def config_dir() -> Path:
+    """Directory holding config.yaml, providers.yaml, workspaces.yaml, mcp.json."""
+    d = app_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def artifacts_dir() -> Path:
+    """Directory for binary tool-result artifacts (PNGs, etc.) — files, not DB blobs."""
+    d = app_dir() / "artifacts"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def logs_dir() -> Path:
+    """Directory for rotating log files."""
+    d = app_dir() / "logs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def skills_dir() -> Path:
+    """Directory holding the user's own skills markdown files."""
+    d = app_dir() / "skills"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def workflows_dir() -> Path:
+    """Directory holding stored named workflows (Phase 10)."""
+    d = app_dir() / "workflows"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def db_path() -> Path:
+    """Path to the SQLite database file (created lazily by aida.persistence)."""
+    return app_dir() / "aida.db"
+
+
+def default_records_dir() -> Path:
+    """Default location for human-readable conversation records.
+
+    Overridable per-install via ``config.yaml``'s ``records_dir`` — callers
+    that need the *effective* records dir should read it from settings, not
+    call this directly, except as the fallback default.
+    """
+    return Path.home() / "Documents" / DEFAULT_RECORDS_DIRNAME
+
+
+def ensure_records_dir(path: Path | None = None) -> Path:
+    """Create (if needed) and return the records dir, honoring an override."""
+    target = Path(path).expanduser() if path else default_records_dir()
+    target.mkdir(parents=True, exist_ok=True)
+    return target

aida/config/secrets.py

@@ -0,0 +1,70 @@
+"""Secret storage: OS keychain via ``keyring``, with env-var override.
+
+Hard rule (PLAN.md §4): secrets never touch ``~/.aida/*.yaml`` or ``*.json``.
+``providers.yaml`` stores only a ``secret_ref`` (a profile name); the actual
+API key / ANL username lives in the OS keychain, or — for headless / CI /
+pipeline use — in an ``AIDA_SECRET_<PROFILE>`` environment variable, checked
+first so it always wins in non-interactive contexts.
+
+This module never logs a secret value, and its own returned values must
+never be handed to any of the YAML/JSON writers in ``aida.config.settings``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+
+import keyring
+from keyring.errors import KeyringError
+
+SERVICE_NAME = "aida"
+ENV_PREFIX = "AIDA_SECRET_"
+
+
+def _env_var_name(profile: str) -> str:
+    return ENV_PREFIX + profile.upper().replace("-", "_")
+
+
+def get_secret(profile: str) -> str | None:
+    """Return the secret for ``profile``, or None if not set anywhere.
+
+    Lookup order: environment variable override, then OS keychain.
+    """
+    import os
+
+    env_val = os.environ.get(_env_var_name(profile))
+    if env_val is not None:
+        return env_val
+
+    try:
+        return keyring.get_password(SERVICE_NAME, profile)
+    except KeyringError:
+        return None
+
+
+def set_secret(profile: str, value: str) -> None:
+    """Store a secret for ``profile`` in the OS keychain.
+
+    Does not touch environment variables — an env override, if set, will
+    keep taking precedence over whatever is stored here until unset.
+    """
+    keyring.set_password(SERVICE_NAME, profile, value)
+
+
+def delete_secret(profile: str) -> None:
+    """Remove a stored secret for ``profile`` from the OS keychain, if present."""
+    with contextlib.suppress(KeyringError):
+        keyring.delete_password(SERVICE_NAME, profile)
+
+
+def keyring_available() -> bool:
+    """Best-effort check that a usable keyring backend is configured.
+
+    Used by ``aida doctor`` — a missing/broken backend (common on fresh
+    Linux CI images) is reported, not raised.
+    """
+    try:
+        backend = keyring.get_keyring()
+        return backend is not None and "fail" not in type(backend).__name__.lower()
+    except Exception:
+        return False

aida/config/settings.py

@@ -0,0 +1,354 @@
+"""Load, validate, and default AIDA's YAML/JSON config files.
+
+Pattern (pyIrena rule, PLAN.md §10.3 / Phase 1 tasks): **old configs must
+always load.** Every field has a default; a config file that predates a new
+field simply gets that field's default rather than failing to load. Config
+schema versioning (``config_version``) is present from day one so future
+migrations have something to key off of.
+
+No secret value is ever read from or written to these files — see
+``aida.config.secrets``.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from aida.config.paths import config_dir
+
+CURRENT_CONFIG_VERSION = 1
+
+
+# --------------------------------------------------------------------------
+# config.yaml
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class AppConfig:
+    """General settings: paths, safety default, UI prefs, log level."""
+
+    config_version: int = CURRENT_CONFIG_VERSION
+    records_dir: str | None = None  # None -> aida.config.paths.default_records_dir()
+    log_level: str = "INFO"
+    default_safety_mode: str = "confirm"  # "relaxed" | "confirm"
+    theme: str = "system"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AppConfig:
+        known = {f for f in cls.__dataclass_fields__}
+        filtered = {k: v for k, v in (data or {}).items() if k in known}
+        return cls(**filtered)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "config_version": self.config_version,
+            "records_dir": self.records_dir,
+            "log_level": self.log_level,
+            "default_safety_mode": self.default_safety_mode,
+            "theme": self.theme,
+        }
+
+
+# --------------------------------------------------------------------------
+# providers.yaml
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class ProviderProfile:
+    """A named provider profile. NO secrets inline — secret refs only."""
+
+    name: str
+    kind: str = "openai_compat"  # "openai_compat" | "anthropic"
+    base_url: str | None = None
+    model: str = ""
+    secret_ref: str | None = None  # key into aida.config.secrets, not a value
+    capability_notes: str = ""
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict[str, Any]) -> ProviderProfile:
+        return cls(
+            name=name,
+            kind=data.get("kind", "openai_compat"),
+            base_url=data.get("base_url"),
+            model=data.get("model", ""),
+            secret_ref=data.get("secret_ref"),
+            capability_notes=data.get("capability_notes", ""),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "base_url": self.base_url,
+            "model": self.model,
+            "secret_ref": self.secret_ref,
+            "capability_notes": self.capability_notes,
+        }
+
+
+@dataclass
+class ProvidersConfig:
+    config_version: int = CURRENT_CONFIG_VERSION
+    profiles: dict[str, ProviderProfile] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProvidersConfig:
+        data = data or {}
+        profiles = {
+            name: ProviderProfile.from_dict(name, pdata)
+            for name, pdata in (data.get("profiles") or {}).items()
+        }
+        return cls(
+            config_version=data.get("config_version", CURRENT_CONFIG_VERSION),
+            profiles=profiles,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "config_version": self.config_version,
+            "profiles": {name: p.to_dict() for name, p in self.profiles.items()},
+        }
+
+
+# --------------------------------------------------------------------------
+# workspaces.yaml
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class WorkspaceConfig:
+    name: str
+    profile: str | None = None
+    source_folders: list[str] = field(default_factory=list)
+    target_folder: str | None = None
+    sidecar_folder_name: str = "figures"
+    mcp_group: str = "none"
+    skills: list[str] = field(default_factory=list)
+    system_prompt: str | None = None
+    safety: str = "confirm"  # "relaxed" | "confirm"
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict[str, Any]) -> WorkspaceConfig:
+        return cls(
+            name=name,
+            profile=data.get("profile"),
+            source_folders=list(data.get("source_folders", [])),
+            target_folder=data.get("target_folder"),
+            sidecar_folder_name=data.get("sidecar_folder_name", "figures"),
+            mcp_group=data.get("mcp_group", "none"),
+            skills=list(data.get("skills", [])),
+            system_prompt=data.get("system_prompt"),
+            safety=data.get("safety", "confirm"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "profile": self.profile,
+            "source_folders": self.source_folders,
+            "target_folder": self.target_folder,
+            "sidecar_folder_name": self.sidecar_folder_name,
+            "mcp_group": self.mcp_group,
+            "skills": self.skills,
+            "system_prompt": self.system_prompt,
+            "safety": self.safety,
+        }
+
+
+@dataclass
+class WorkspacesConfig:
+    config_version: int = CURRENT_CONFIG_VERSION
+    workspaces: dict[str, WorkspaceConfig] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> WorkspacesConfig:
+        data = data or {}
+        workspaces = {
+            name: WorkspaceConfig.from_dict(name, wdata)
+            for name, wdata in (data.get("workspaces") or {}).items()
+        }
+        return cls(
+            config_version=data.get("config_version", CURRENT_CONFIG_VERSION),
+            workspaces=workspaces,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "config_version": self.config_version,
+            "workspaces": {name: w.to_dict() for name, w in self.workspaces.items()},
+        }
+
+
+# --------------------------------------------------------------------------
+# mcp.json (standard-style + aida extras)
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class McpServerConfig:
+    name: str
+    command: str = ""
+    args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    groups: list[str] = field(default_factory=list)
+    skills: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict[str, Any]) -> McpServerConfig:
+        return cls(
+            name=name,
+            command=data.get("command", ""),
+            args=list(data.get("args", [])),
+            env=dict(data.get("env", {})),
+            groups=list(data.get("groups", [])),
+            skills=list(data.get("skills", [])),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "command": self.command,
+            "args": self.args,
+            "env": self.env,
+            "groups": self.groups,
+            "skills": self.skills,
+        }
+
+
+@dataclass
+class McpConfig:
+    config_version: int = CURRENT_CONFIG_VERSION
+    servers: dict[str, McpServerConfig] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> McpConfig:
+        data = data or {}
+        servers = {
+            name: McpServerConfig.from_dict(name, sdata)
+            for name, sdata in (data.get("mcpServers") or {}).items()
+        }
+        return cls(
+            config_version=data.get("config_version", CURRENT_CONFIG_VERSION),
+            servers=servers,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "config_version": self.config_version,
+            "mcpServers": {name: s.to_dict() for name, s in self.servers.items()},
+        }
+
+
+# --------------------------------------------------------------------------
+# Loading / saving
+# --------------------------------------------------------------------------
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        return yaml.safe_load(fh) or {}
+
+
+def _write_yaml(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as fh:
+        yaml.safe_dump(data, fh, sort_keys=False)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        return json.load(fh) or {}
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+
+
+def load_app_config(base_dir: Path | None = None) -> AppConfig:
+    path = (base_dir or config_dir()) / "config.yaml"
+    return AppConfig.from_dict(_read_yaml(path))
+
+
+def save_app_config(cfg: AppConfig, base_dir: Path | None = None) -> Path:
+    path = (base_dir or config_dir()) / "config.yaml"
+    _write_yaml(path, cfg.to_dict())
+    return path
+
+
+def load_providers_config(base_dir: Path | None = None) -> ProvidersConfig:
+    path = (base_dir or config_dir()) / "providers.yaml"
+    return ProvidersConfig.from_dict(_read_yaml(path))
+
+
+def save_providers_config(cfg: ProvidersConfig, base_dir: Path | None = None) -> Path:
+    path = (base_dir or config_dir()) / "providers.yaml"
+    _write_yaml(path, cfg.to_dict())
+    return path
+
+
+def load_workspaces_config(base_dir: Path | None = None) -> WorkspacesConfig:
+    path = (base_dir or config_dir()) / "workspaces.yaml"
+    return WorkspacesConfig.from_dict(_read_yaml(path))
+
+
+def save_workspaces_config(cfg: WorkspacesConfig, base_dir: Path | None = None) -> Path:
+    path = (base_dir or config_dir()) / "workspaces.yaml"
+    _write_yaml(path, cfg.to_dict())
+    return path
+
+
+def load_mcp_config(base_dir: Path | None = None) -> McpConfig:
+    path = (base_dir or config_dir()) / "mcp.json"
+    return McpConfig.from_dict(_read_json(path))
+
+
+def save_mcp_config(cfg: McpConfig, base_dir: Path | None = None) -> Path:
+    path = (base_dir or config_dir()) / "mcp.json"
+    _write_json(path, cfg.to_dict())
+    return path
+
+
+@dataclass
+class Settings:
+    """Bundle of everything loaded from ``~/.aida`` for one process."""
+
+    app: AppConfig
+    providers: ProvidersConfig
+    workspaces: WorkspacesConfig
+    mcp: McpConfig
+
+
+def load_settings(base_dir: Path | None = None) -> Settings:
+    """Load all four config files, defaulting anything missing.
+
+    Also ensures the files exist on disk on first run (writing out the
+    defaults), per the Phase 1 acceptance criterion "first run creates
+    ~/.aida with valid default configs".
+    """
+    base = base_dir or config_dir()
+    app = load_app_config(base)
+    providers = load_providers_config(base)
+    workspaces = load_workspaces_config(base)
+    mcp = load_mcp_config(base)
+
+    if not (base / "config.yaml").exists():
+        save_app_config(app, base)
+    if not (base / "providers.yaml").exists():
+        save_providers_config(providers, base)
+    if not (base / "workspaces.yaml").exists():
+        save_workspaces_config(workspaces, base)
+    if not (base / "mcp.json").exists():
+        save_mcp_config(mcp, base)
+
+    return Settings(app=app, providers=providers, workspaces=workspaces, mcp=mcp)

aida/core/__init__.py

@@ -0,0 +1 @@
+"""Agent core: agent loop, conversation, events, context, permissions, workflows. Never imports Qt (see PLAN.md section 3). Filled in starting Phase 2."""

aida/documents/__init__.py

@@ -0,0 +1 @@
+"""Document readers/writers (PDF, DOCX, XLSX, PPTX, MD, TXT, code). Never imports Qt. Filled in starting Phase 6."""

aida/knowledge/__init__.py

@@ -0,0 +1 @@
+"""Skills files and RAG (retrieval-augmented generation). Never imports Qt. Filled in starting Phase 8."""

aida/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP manager: stdio servers, groups, typed result artifacts, skills linkage. Never imports Qt. Filled in starting Phase 3."""

aida/persistence/__init__.py

@@ -0,0 +1 @@
+"""SQLite persistence: conversations, messages, tool calls, artifact metadata. Never imports Qt. Filled in starting Phase 4."""

aida/providers/__init__.py

@@ -0,0 +1 @@
+"""LLM/embedding provider layer (openai-compat + Anthropic/Argo). Never imports Qt. Filled in starting Phase 2."""

aida/ui/__init__.py

@@ -0,0 +1 @@
+"""AIDA frontends. Only aida.ui.qt may import Qt, and only through aida.ui.qt._qt."""

aida/ui/qt/__init__.py

@@ -0,0 +1 @@
+"""PySide6 desktop GUI. All Qt imports must go through _qt.py (see that module). Filled in starting Phase 5."""

aida/ui/qt/_qt.py

@@ -0,0 +1,22 @@
+"""Single Qt import shim (pyIrena pattern).
+
+Every Qt import anywhere in AIDA must go through this module, so that:
+
+- normalizing between PySide6/PyQt6 (if ever needed) touches one file, and
+- the layering contract test (``tests/test_contract_layering.py``) can
+  reliably assert "no Qt import outside aida.ui" by checking for direct
+  ``PySide6``/``PyQt6`` imports anywhere else in the tree.
+
+Phase 1 ships no GUI, so this shim is currently unused scaffolding for
+Phase 5. It intentionally does not import PySide6 yet — doing so would add
+a hard runtime dependency to a package whose ``gui`` extra is optional.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - exercised once PySide6 is an installed extra
+    from PySide6 import QtCore, QtGui, QtWidgets  # noqa: F401
+
+    QT_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    QT_AVAILABLE = False

aida/workspace/__init__.py

@@ -0,0 +1 @@
+"""Workspace files, search, and the allowed-folders safety model. Never imports Qt. Filled in starting Phase 4/6."""

aida_workbench-0.0.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: aida-workbench
+Version: 0.0.1
+Summary: AIDA — AI Data Assistant: a local scientific agent workbench.
+Project-URL: Homepage, https://github.com/jilavsky/aida
+Project-URL: Repository, https://github.com/jilavsky/aida
+Project-URL: Issues, https://github.com/jilavsky/aida/issues
+Author-email: Jan Ilavsky <jilavsky@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.34
+Requires-Dist: keyring>=24.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: openai>=1.40
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: openpyxl>=3.1; extra == 'docs'
+Requires-Dist: pymupdf>=1.24; extra == 'docs'
+Requires-Dist: python-docx>=1.1; extra == 'docs'
+Requires-Dist: python-pptx>=0.6.23; extra == 'docs'
+Provides-Extra: gui
+Requires-Dist: pyside6>=6.6; extra == 'gui'
+Provides-Extra: rag
+Requires-Dist: chromadb>=0.5; extra == 'rag'
+Description-Content-Type: text/markdown
+
+# AIDA — AI Data Assistant
+
+> **Status: pre-alpha.** AIDA is under active, phased development (see
+> `PLAN.md`). Nothing here is stable yet; APIs, config formats, and CLI
+> commands will change without notice until Phase 5 (first GUI release).
+
+AIDA is a local scientific agent workbench: a simple, reliable GUI (and CLI)
+for using AI agents in scientific work — conversation with local or cloud
+LLMs, correct use of domain MCP servers (pyIrena, bait_mcp, ...), correct
+display of rich tool results (especially PNG plots), reading and producing
+documents, and controlled access to the user's data folders.
+
+It is built for pyIrena and USAXS-instrument users and is deliberately **not**
+a general-purpose AI platform — see `PLAN.md` §1 for the full rationale.
+
+## Install (development)
+
+```bash
+git clone https://github.com/jilavsky/aida.git
+cd aida
+conda env create -f environment.yml   # or: pip install -e ".[dev]"
+conda activate aida
+aida doctor
+```
+
+## Status
+
+Following the phased plan in [`PLAN.md`](PLAN.md); per-phase checklists live
+under [`planning/`](planning/). Phase 1 (this scaffold) delivers packaging,
+configuration, logging, and CI — no agent functionality yet.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

aida_workbench-0.0.1.dist-info/RECORD

@@ -0,0 +1,29 @@
+aida/__init__.py,sha256=F_SklSHWRvU7uCTQSMV50S_Hbn5njZpwdl9ZyOsR5Lo,165
+aida/artifacts/__init__.py,sha256=Qe9eHNndbfE62wEunOW4mnPG4BGOiWityhdfPqLG0ak,125
+aida/cli/__init__.py,sha256=q0oIhQqryClWVSZ7IMa6GgGrMwVxtUlmeKu-NCB1TKQ,207
+aida/cli/__main__.py,sha256=uIgMYSsugUCERSVXF_FLdnm2iBWOq84MPeKIuZuyJbA,1808
+aida/cli/chat.py,sha256=iZkOhtGDU5w-FXgC5tzUv-2P5vQpGG21ku7VukLLmX8,406
+aida/cli/config_cmds.py,sha256=LaMlohMkCSQCASYt4PSNgYvNdQHF6XZ250Wa4yogw9o,558
+aida/cli/doctor.py,sha256=eD7KFEzfbv-YbdnAfiCUr8uHL19kuCGfoj5EwMl9QwI,5434
+aida/cli/run.py,sha256=JS-Z2SqTrEPQ4MCVV7oFYYIYLnA32EC8YKAsrvAodJA,378
+aida/coding/__init__.py,sha256=dgRdxFHf6plXRmi6J2NKa8O1XWQ1dsO0PdLBLMfPiAw,119
+aida/config/__init__.py,sha256=0FrDY7YkqGAjGpV9DSxb6j9nILd4JPietmkq6FD5qLM,146
+aida/config/logging_setup.py,sha256=AVour9N5H-iR25eL-rGqXfGK-SFk3YfXKbdtvmr6pg8,2012
+aida/config/paths.py,sha256=2pOeRkU1wzfYUztfCmyXmlJq44PTYmLpWtuhX5F4xJY,2805
+aida/config/secrets.py,sha256=DSi8Gds6rUGNSIjzJHo33iTI4q8WYC7QanWW6f5ikqo,2231
+aida/config/settings.py,sha256=T55t8EFMugF2N4pdnxc98ClEDNEJEEanVVwYiEvI5sE,11529
+aida/core/__init__.py,sha256=czMLl7YTZzy_z3agwzq0LFhXOdDYRd7NlTfRSImopw8,155
+aida/documents/__init__.py,sha256=2e5Qi2OBquynjNvgenDN4npX0Ze-JdjjPtWW-xd1Pww,117
+aida/knowledge/__init__.py,sha256=hRzAHPREnaN3ceZSLHvAeDF1PjmiOiVSrpwZmlqmp-w,107
+aida/mcp/__init__.py,sha256=Jw5BHyF12tZmgeEEY7dHhm6oZq699rmz6DaHKZKwTj8,128
+aida/persistence/__init__.py,sha256=wSXu1dubV3GhEQJc78y3HRT8BYpghOfDKs9jkhEYdLo,128
+aida/providers/__init__.py,sha256=i8IcazHlg_bqCAxvuo7_h-KlurfAsnuXeZ9tY9iP1f0,115
+aida/ui/__init__.py,sha256=r2G1z_LdgENDO_eIrKc4cNQsx_hI_VRHCMOURzBRNSI,86
+aida/ui/qt/__init__.py,sha256=jYt_0Z0YiUeZ4abc0fLLlCf9eqevX77ZNtm9Ac9w7rw,112
+aida/ui/qt/_qt.py,sha256=g7veZ_-hrc785MFLmy8gOSTh9vevaI5pRxFPdEnEBYs,881
+aida/workspace/__init__.py,sha256=V0yE2Ppu5g4_PjWOTE1w3tvXPMb4nprim_kjKxsfhmU,117
+aida_workbench-0.0.1.dist-info/METADATA,sha256=wCSwddqLCNBqWJppGwL34w1MXPBHUdtmjUBRcZ0RSic,2668
+aida_workbench-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+aida_workbench-0.0.1.dist-info/entry_points.txt,sha256=24qIt3MpLiwxMXWteaoEzR0SzLiM956CaJ3uFabRRCM,86
+aida_workbench-0.0.1.dist-info/licenses/LICENSE,sha256=622TYrxFs9J2n7JoMJ5akAiKUv7cgmwX-QCp4eLHBhE,1068
+aida_workbench-0.0.1.dist-info/RECORD,,

aida_workbench-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aida_workbench-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+aida = aida.cli.__main__:main
+aida-gui = aida.cli.__main__:main_gui

aida_workbench-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Ilavsky
+
+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.