local-data-studio 1.0.0__py3-none-any.whl

local_data_studio/__init__.py

@@ -0,0 +1,3 @@
+"""Local Data Studio package."""
+
+__version__ = "0.1.0"

local_data_studio/__main__.py

@@ -0,0 +1,6 @@
+"""Run Local Data Studio with ``python -m local_data_studio``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

local_data_studio/app.py

@@ -0,0 +1,150 @@
+"""FastAPI application assembly for Local Data Studio."""
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from .server.api.analysis import column_stats, count_rows, llm_models, nl_query, run_eda, run_query, search
+from .server.api.analysis import router as analysis_router
+from .server.api.atlas_proxy import router as atlas_proxy_router
+from .server.api.atlas_proxy import stop_atlas_instance
+from .server.api.datasets import (
+    column_sample,
+    embedder_models,
+    get_config,
+    get_schema,
+    list_files,
+    preview,
+    raw_file,
+    raw_row,
+    upload_files,
+)
+from .server.api.datasets import (
+    router as datasets_router,
+)
+from .server.api.jobs import (
+    cancel_job,
+    get_job,
+    start_atlas_job,
+    start_atlas_query_job,
+    start_count_job,
+    start_eda_job,
+    start_eda_query_job,
+    start_index_job,
+    start_query_job,
+    start_search_job,
+    start_stats_job,
+)
+from .server.api.jobs import (
+    router as jobs_router,
+)
+from .server.api.mutations import delete_column, delete_row
+from .server.api.mutations import router as mutations_router
+from .server.api.schemas import (
+    AtlasQueryRequest,
+    AtlasRequest,
+    CountJobRequest,
+    DeleteColumnRequest,
+    DeleteRowRequest,
+    EdaQueryRequest,
+    EdaRequest,
+    IndexJobRequest,
+    NLQueryRequest,
+    QueryRequest,
+    RawRowRequest,
+    SearchJobRequest,
+    StatsJobRequest,
+)
+from .server.api.static import NoCacheStaticFiles, mount_static_files
+from .server.atlas_components.runtime import AtlasRuntime
+from .server.config import ATLAS_MAX_INSTANCES
+from .server.jobs import JobStore
+
+
+def create_app(*, job_store: JobStore | None = None, atlas_runtime: AtlasRuntime | None = None) -> FastAPI:
+    """Assemble the application with API routes before static catch-all mounts.
+
+    Returns:
+        A new application instance. Callers own the instance and may add routes.
+    """
+    owned_job_store = job_store or JobStore()
+    owned_atlas_runtime = atlas_runtime or AtlasRuntime(max_instances=ATLAS_MAX_INSTANCES)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+        await owned_atlas_runtime.start_proxy_client()
+        try:
+            yield
+        finally:
+            owned_atlas_runtime.begin_shutdown()
+            owned_job_store.begin_shutdown()
+            await asyncio.to_thread(owned_job_store.wait_for_idle, 10.0)
+            await asyncio.to_thread(owned_atlas_runtime.terminate_all)
+            await owned_atlas_runtime.close_proxy_client()
+            owned_job_store.shutdown(wait_timeout=0.0)
+
+    application = FastAPI(title="Data Viewer", lifespan=lifespan)
+    application.state.job_store = owned_job_store
+    application.state.atlas_runtime = owned_atlas_runtime
+    application.include_router(datasets_router)
+    application.include_router(analysis_router)
+    application.include_router(jobs_router)
+    application.include_router(mutations_router)
+    application.include_router(atlas_proxy_router)
+    mount_static_files(application)
+    return application
+
+
+app = create_app()
+
+
+__all__ = [
+    "AtlasQueryRequest",
+    "AtlasRequest",
+    "CountJobRequest",
+    "DeleteColumnRequest",
+    "DeleteRowRequest",
+    "EdaQueryRequest",
+    "EdaRequest",
+    "IndexJobRequest",
+    "NLQueryRequest",
+    "NoCacheStaticFiles",
+    "QueryRequest",
+    "RawRowRequest",
+    "SearchJobRequest",
+    "StatsJobRequest",
+    "app",
+    "cancel_job",
+    "column_sample",
+    "column_stats",
+    "count_rows",
+    "create_app",
+    "delete_column",
+    "delete_row",
+    "embedder_models",
+    "get_config",
+    "get_job",
+    "get_schema",
+    "list_files",
+    "llm_models",
+    "nl_query",
+    "preview",
+    "raw_file",
+    "raw_row",
+    "run_eda",
+    "run_query",
+    "search",
+    "start_atlas_job",
+    "start_atlas_query_job",
+    "start_count_job",
+    "start_eda_job",
+    "start_eda_query_job",
+    "start_index_job",
+    "start_query_job",
+    "start_search_job",
+    "start_stats_job",
+    "stop_atlas_instance",
+    "upload_files",
+]

local_data_studio/cli.py

@@ -0,0 +1,154 @@
+"""Command-line entrypoint for Local Data Studio."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+import uvicorn
+
+from .runtime_config import CONFIG_FILE_ENV, apply_settings_environment, config_section, read_runtime_config
+
+PATH_ENV_KEYS: dict[str, str] = {
+    "workspace_dir": "LOCAL_DATA_STUDIO_WORKSPACE_DIR",
+    "env_file": "LOCAL_DATA_STUDIO_ENV_FILE",
+    "data_dir": "DATA_DIR",
+    "data_file": "DATA_FILE",
+    "cache_dir": "CACHE_DIR",
+    "models_dir": "EMBEDDER_MODELS_DIR",
+    "file_serve_roots": "FILE_SERVE_ROOTS",
+    "vis_exclude_dirs": "VIS_EXCLUDE_DIRS",
+    "vis_exclude_files": "VIS_EXCLUDE_FILES",
+}
+
+
+def _set_path_env(name: str, value: str | None, *, overwrite: bool = True) -> None:
+    if value:
+        if overwrite or name not in os.environ:
+            os.environ[name] = str(Path(value).expanduser())
+
+
+def _resolve_path(value: str, base_dir: Path) -> str:
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        path = base_dir / path
+    return str(path.resolve())
+
+
+def _coerce_path_setting(value: Any, base_dir: Path) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        stripped = value.strip()
+        return _resolve_path(stripped, base_dir) if stripped else None
+    if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray, str)):
+        resolved = [_resolve_path(str(item), base_dir) for item in value if str(item).strip()]
+        return ",".join(resolved) if resolved else None
+    return str(value)
+
+
+def _workspace_from(args: argparse.Namespace, config: Mapping[str, Any], config_path: Path | None) -> Path:
+    paths = config_section(config, "paths")
+    raw_workspace = args.workspace_dir or os.environ.get("LOCAL_DATA_STUDIO_WORKSPACE_DIR") or paths.get("workspace_dir")
+    if raw_workspace:
+        base_dir = config_path.parent if config_path else Path.cwd()
+        return Path(_resolve_path(str(raw_workspace), base_dir))
+    return Path.cwd().resolve()
+
+
+def _apply_config_environment(config: Mapping[str, Any], workspace_dir: Path) -> None:
+    paths = config_section(config, "paths")
+    _set_path_env("LOCAL_DATA_STUDIO_WORKSPACE_DIR", str(workspace_dir), overwrite=False)
+    for key, env_name in PATH_ENV_KEYS.items():
+        if key == "workspace_dir":
+            continue
+        coerced = _coerce_path_setting(paths.get(key), workspace_dir)
+        _set_path_env(env_name, coerced, overwrite=False)
+
+
+def configure_runtime_environment(args: argparse.Namespace) -> tuple[str, int, bool]:
+    """Resolve CLI, environment, and TOML settings before importing the app.
+
+    Explicit CLI paths take precedence over environment and config values. Relative
+    config paths are resolved from the config file; other defaults use the workspace.
+
+    Returns:
+        The host, port, and reload values passed to Uvicorn.
+
+    Raises:
+        OSError: The requested config file cannot be read.
+        tomllib.TOMLDecodeError: The config file is not valid TOML.
+    """
+    config, config_path = read_runtime_config(args.config)
+    if config_path:
+        os.environ[CONFIG_FILE_ENV] = str(config_path)
+    workspace_dir = _workspace_from(args, config, config_path)
+    _apply_config_environment(config, workspace_dir)
+    apply_settings_environment(config)
+
+    _set_path_env("LOCAL_DATA_STUDIO_WORKSPACE_DIR", str(workspace_dir), overwrite=bool(args.workspace_dir))
+    _set_path_env("LOCAL_DATA_STUDIO_ENV_FILE", args.env_file)
+    _set_path_env("DATA_DIR", args.data_dir)
+    _set_path_env("DATA_FILE", args.data_file)
+    _set_path_env("CACHE_DIR", args.cache_dir)
+    _set_path_env("EMBEDDER_MODELS_DIR", args.models_dir)
+    if args.file_serve_roots:
+        os.environ["FILE_SERVE_ROOTS"] = ",".join(str(Path(item).expanduser()) for item in args.file_serve_roots)
+
+    server = config_section(config, "server")
+    host = args.host or os.environ.get("LOCAL_DATA_STUDIO_HOST") or str(server.get("host") or "127.0.0.1")
+    port = args.port or int(os.environ.get("LOCAL_DATA_STUDIO_PORT") or server.get("port") or 8000)
+    reload = bool(args.reload if args.reload is not None else _coerce_bool(os.environ.get("LOCAL_DATA_STUDIO_RELOAD"), server.get("reload", False)))
+    return host, port, reload
+
+
+def _coerce_bool(value: Any, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    normalized = str(value).strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    return default
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser without reading runtime configuration."""
+    parser = argparse.ArgumentParser(description="Run the Local Data Studio web app.")
+    parser.add_argument("--config", help="Path to a Local Data Studio TOML config file.")
+    parser.add_argument("--workspace-dir", help="Base directory for .env, data, cache, and models/embedder defaults.")
+    parser.add_argument("--env-file", help="Path to the .env file to load.")
+    parser.add_argument("--host", help="Host interface for the local web server.")
+    parser.add_argument("--port", type=int, help="Port for the local web server.")
+    parser.add_argument("--cache-dir", help="Directory for Local Data Studio cache files.")
+    parser.add_argument("--models-dir", help="Directory containing HuggingFace encoder model directories.")
+    parser.add_argument("--file-serve-roots", nargs="+", help="Directories from which local image files may be served.")
+    parser.add_argument("--reload", action=argparse.BooleanOptionalAction, default=None, help="Enable uvicorn reload for local development.")
+
+    data_source = parser.add_mutually_exclusive_group()
+    data_source.add_argument("--data-dir", help="Directory to search for datasets.")
+    data_source.add_argument("--data-file", help="Single dataset file to open.")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Configure the workspace and run the Uvicorn web server.
+
+    Args:
+        argv: Arguments without the executable name. ``None`` reads ``sys.argv``.
+    """
+    args = build_parser().parse_args(argv)
+    host, port, reload = configure_runtime_environment(args)
+
+    uvicorn.run(
+        "local_data_studio.app:app",
+        host=host,
+        port=port,
+        reload=reload,
+    )

local_data_studio/runtime_config.py

@@ -0,0 +1,77 @@
+"""Shared loading helpers for Local Data Studio TOML configuration."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILE_ENV = "LOCAL_DATA_STUDIO_CONFIG_FILE"
+
+# These TOML keys mirror environment-backed Settings fields. Paths remain in
+# [paths], while [settings] owns the operational EDA, Atlas, and deletion
+# controls so a checked local TOML can replace a large .env file.
+SETTINGS_ENV_KEYS: dict[str, str] = {
+    "eda_row_limit": "EDA_ROW_LIMIT",
+    "allow_delete_data": "ALLOW_DELETE_DATA",
+    "eda_cell_max_chars": "EDA_CELL_MAX_CHARS",
+    "eda_nested_policy": "EDA_NESTED_POLICY",
+    "eda_cache_max_bytes": "EDA_CACHE_MAX_BYTES",
+    "atlas_host": "ATLAS_HOST",
+    "atlas_port": "ATLAS_PORT",
+    "atlas_max_instances": "ATLAS_MAX_INSTANCES",
+    "atlas_sample": "ATLAS_SAMPLE",
+    "atlas_batch_size": "ATLAS_BATCH_SIZE",
+    "atlas_cache_max_bytes": "ATLAS_CACHE_MAX_BYTES",
+    "atlas_text_max_chars": "ATLAS_TEXT_MAX_CHARS",
+    "atlas_embedding_dtype": "ATLAS_EMBEDDING_DTYPE",
+    "atlas_umap_projection_mode": "ATLAS_UMAP_PROJECTION_MODE",
+    "atlas_umap_anchor_sample": "ATLAS_UMAP_ANCHOR_SAMPLE",
+    "atlas_trust_remote_code": "ATLAS_TRUST_REMOTE_CODE",
+}
+
+
+def read_runtime_config(path: str | None) -> tuple[dict[str, Any], Path | None]:
+    """Read an optional TOML configuration file.
+
+    Args:
+        path: Explicit path, or ``None`` to use ``LOCAL_DATA_STUDIO_CONFIG_FILE``.
+
+    Returns:
+        The parsed root table and resolved source path. Both are empty when no
+        configuration file is selected.
+
+    Raises:
+        OSError: The selected file cannot be read.
+        tomllib.TOMLDecodeError: The selected file is not valid TOML.
+    """
+    selected = path or os.environ.get(CONFIG_FILE_ENV)
+    if not selected:
+        return {}, None
+    config_path = Path(selected).expanduser().resolve()
+    with config_path.open("rb") as handle:
+        loaded = tomllib.load(handle)
+    return loaded, config_path
+
+
+def config_section(config: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    """Return a mapping-valued root section, or an empty mapping."""
+    value = config.get(name)
+    return value if isinstance(value, Mapping) else {}
+
+
+def apply_settings_environment(config: Mapping[str, Any]) -> None:
+    """Expose `[settings]` values through the existing Settings environment API.
+
+    Existing OS environment variables are never replaced. This preserves the
+    documented precedence over TOML while allowing Pydantic Settings to keep
+    its existing validation and `.env` fallback behavior.
+    """
+    settings = config_section(config, "settings")
+    for key, environment_name in SETTINGS_ENV_KEYS.items():
+        value = settings.get(key)
+        if value is None or environment_name in os.environ:
+            continue
+        os.environ[environment_name] = str(value).lower() if isinstance(value, bool) else str(value)

local_data_studio/server/__init__.py

@@ -0,0 +1 @@
+"""Backend package."""

local_data_studio/server/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API routers for Local Data Studio."""

local_data_studio/server/api/analysis.py

@@ -0,0 +1,123 @@
+"""Synchronous analysis and SQL endpoints."""
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+
+from ..config import DEFAULT_LIMIT, DEFAULT_SAMPLE
+from ..db import (
+    build_table_response,
+    count_relation_rows,
+    describe_relation,
+    fetch_rows_with_rowid,
+    normalize_pagination,
+    open_connection,
+    quote_ident,
+    relation_sql,
+    relation_with_rowid_sql,
+)
+from ..deleted_rows import deleted_row_ids_for
+from ..files import resolve_data_file
+from ..llm import generate_sql_request, public_llm_models
+from ..sql import execute_query_guarded
+from ..stats import compute_column_stats
+from .schemas import EdaRequest, NLQueryRequest, QueryRequest
+from .services import eda_reports_service, reject_large_sync_operation
+
+router = APIRouter()
+
+
+@router.get("/api/llm_models")
+def llm_models() -> dict[str, Any]:
+    """Return server-managed model profiles without secrets or endpoints."""
+    return public_llm_models()
+
+
+@router.get("/api/column_stats")
+def column_stats(file: str = Query(...), sample: int | None = Query(DEFAULT_SAMPLE)) -> dict[str, Any]:
+    """Return bounded sample statistics, rejecting large synchronous scans."""
+    path = resolve_data_file(file)
+    reject_large_sync_operation(path, "synchronous column stats")
+    return compute_column_stats(file, path, sample if sample is not None else DEFAULT_SAMPLE)
+
+
+@router.post("/api/eda")
+def run_eda(payload: EdaRequest) -> dict[str, Any]:
+    """Generate or reuse an EDA report and return its cache URL."""
+    path = resolve_data_file(payload.file)
+    return eda_reports_service().generate_dataset_eda_report(
+        file_name=payload.file,
+        path=path,
+        sample=payload.sample,
+        mode=payload.mode,
+        force=payload.force,
+    )
+
+
+@router.post("/api/nl_query")
+def nl_query(payload: NLQueryRequest) -> dict[str, Any]:
+    """Generate SQL from a non-empty natural-language prompt and dataset schema."""
+    path = resolve_data_file(payload.file)
+    prompt = payload.prompt.strip()
+    if not prompt:
+        raise HTTPException(status_code=400, detail="prompt must not be empty")
+    relation, params = relation_sql(path)
+    with open_connection() as connection:
+        columns = describe_relation(connection, relation, params)
+    result = generate_sql_request(prompt, columns, payload.sample, payload.model)
+    return {"sql": result.sql, "model": result.model_id, "model_label": result.model_label}
+
+
+@router.get("/api/count")
+def count_rows(file: str = Query(...)) -> dict[str, Any]:
+    """Count rows synchronously only when the dataset is below the safety limit."""
+    path = resolve_data_file(file)
+    reject_large_sync_operation(path, "synchronous row count")
+    return {"file": file, "count": count_relation_rows(path)}
+
+
+@router.get("/api/search")
+def search(
+    file: str = Query(...),
+    query: str = Query(...),
+    limit: int | None = Query(DEFAULT_LIMIT),
+    offset: int | None = Query(0),
+) -> dict[str, Any]:
+    """Search textual columns synchronously with bounded pagination.
+
+    Raises:
+        HTTPException: The query is blank or the dataset requires a background job.
+    """
+    path = resolve_data_file(file)
+    reject_large_sync_operation(path, "synchronous search")
+    deleted_ids = deleted_row_ids_for(path)
+    relation, params = relation_with_rowid_sql(path, deleted_ids)
+    search_term = query.strip()
+    if not search_term:
+        raise HTTPException(status_code=400, detail="query must not be empty")
+    limit_value, offset_value = normalize_pagination(limit, offset)
+
+    with open_connection() as connection:
+        base_relation, base_params = relation_sql(path)
+        columns = describe_relation(connection, base_relation, base_params)
+        text_columns = [column["name"] for column in columns if "CHAR" in column["type"].upper() or "TEXT" in column["type"].upper()]
+        if not text_columns:
+            return build_table_response(file, [column["name"] for column in columns], [], limit_value, offset_value, [])
+        like_clauses = " OR ".join(f"CAST({quote_ident(column)} AS VARCHAR) ILIKE ?" for column in text_columns)
+        values = params + [f"%{search_term}%"] * len(text_columns)
+        search_sql = f"SELECT * FROM ({relation}) WHERE {like_clauses} LIMIT {limit_value} OFFSET {offset_value}"
+        result_columns, rows, row_ids = fetch_rows_with_rowid(connection, search_sql, values)
+    return build_table_response(file, result_columns, rows, limit_value, offset_value, row_ids)
+
+
+@router.post("/api/query")
+def run_query(payload: QueryRequest) -> dict[str, Any]:
+    """Run validated read-only SQL under configured resource limits."""
+    path = resolve_data_file(payload.file)
+    return execute_query_guarded(
+        file_name=payload.file,
+        path=path,
+        sql=payload.sql,
+        limit=payload.limit,
+        offset=payload.offset,
+    )

local_data_studio/server/api/atlas_proxy.py

@@ -0,0 +1,156 @@
+"""Same-origin streaming reverse proxy for registered Atlas instances."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import AsyncIterator, Iterable
+from urllib.parse import urljoin, urlsplit, urlunsplit
+
+import httpx
+from fastapi import APIRouter, HTTPException, Request
+from starlette.background import BackgroundTask
+from starlette.responses import RedirectResponse, StreamingResponse
+
+from ..atlas_components.runtime import AtlasInstance, AtlasRuntime, AtlasRuntimeError
+
+router = APIRouter()
+
+INSTANCE_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{32,64}$")
+HOP_BY_HOP_HEADERS = {
+    b"connection",
+    b"keep-alive",
+    b"proxy-authenticate",
+    b"proxy-authorization",
+    b"te",
+    b"trailer",
+    b"transfer-encoding",
+    b"upgrade",
+}
+PRIVATE_REQUEST_HEADERS = {b"authorization", b"cookie", b"host", b"content-length"}
+PRIVATE_RESPONSE_HEADERS = {b"set-cookie"}
+PROXY_METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+
+
+def _runtime(request: Request) -> AtlasRuntime:
+    return request.app.state.atlas_runtime
+
+
+def _connection_tokens(headers: Iterable[tuple[bytes, bytes]]) -> set[bytes]:
+    tokens: set[bytes] = set()
+    for name, value in headers:
+        if name.lower() == b"connection":
+            tokens.update(token.strip().lower() for token in value.split(b",") if token.strip())
+    return tokens
+
+
+def _filtered_headers(
+    headers: Iterable[tuple[bytes, bytes]],
+    *,
+    private: set[bytes],
+) -> list[tuple[bytes, bytes]]:
+    raw_headers = list(headers)
+    blocked = HOP_BY_HOP_HEADERS | private | _connection_tokens(raw_headers)
+    return [(name, value) for name, value in raw_headers if name.lower() not in blocked]
+
+
+def _resolve_instance(runtime: AtlasRuntime, instance_id: str) -> AtlasInstance:
+    if INSTANCE_ID_PATTERN.fullmatch(instance_id) is None:
+        raise HTTPException(status_code=404, detail="Atlas instance not found")
+    instance = runtime.resolve(instance_id)
+    if instance is None:
+        raise HTTPException(status_code=404, detail="Atlas instance not found")
+    return instance
+
+
+def _upstream_url(request: Request, instance: AtlasInstance) -> httpx.URL:
+    raw_path = request.scope.get("raw_path")
+    if not isinstance(raw_path, bytes):
+        raw_path = request.url.path.encode("utf-8")
+    prefix = f"/atlas/{instance.instance_id}".encode()
+    if not raw_path.startswith(prefix):
+        raise HTTPException(status_code=404, detail="Atlas instance not found")
+    target_path = raw_path[len(prefix) :] or b"/"
+    if not target_path.startswith(b"/"):
+        raise HTTPException(status_code=400, detail="Invalid Atlas proxy path")
+    query = request.scope.get("query_string", b"")
+    raw_target = target_path + (b"?" + query if query else b"")
+    # The host is intentionally constant: request data and child output cannot
+    # turn this route into a general-purpose server-side request proxy.
+    return httpx.URL(scheme="http", host="127.0.0.1", port=instance.port, raw_path=raw_target)
+
+
+def _rewrite_location(value: bytes, *, upstream_url: httpx.URL, instance: AtlasInstance) -> bytes:
+    location = value.decode("latin-1")
+    resolved = urljoin(str(upstream_url), location)
+    parsed = urlsplit(resolved)
+    upstream = urlsplit(str(upstream_url))
+    if (parsed.scheme, parsed.hostname, parsed.port) != (upstream.scheme, upstream.hostname, upstream.port):
+        return value
+    path = parsed.path.lstrip("/")
+    proxy_path = instance.proxy_path + path
+    rewritten = urlunsplit(("", "", proxy_path, parsed.query, parsed.fragment))
+    return rewritten.encode("latin-1")
+
+
+async def _response_body(upstream: httpx.Response) -> AsyncIterator[bytes]:
+    try:
+        async for chunk in upstream.aiter_raw():
+            yield chunk
+    finally:
+        await upstream.aclose()
+
+
+@router.delete("/api/atlas/instances/{instance_id}")
+def stop_atlas_instance(instance_id: str, request: Request) -> dict[str, object]:
+    """Stop one live Atlas child selected by its opaque instance identifier."""
+    runtime = _runtime(request)
+    _resolve_instance(runtime, instance_id)
+    if not runtime.stop(instance_id):
+        raise HTTPException(status_code=404, detail="Atlas instance not found")
+    return {"instance_id": instance_id, "stopped": True}
+
+
+@router.api_route("/atlas/{instance_id}", methods=PROXY_METHODS, include_in_schema=False)
+async def redirect_atlas_root(instance_id: str, request: Request) -> RedirectResponse:
+    """Canonicalize Atlas roots so relative frontend assets resolve correctly."""
+    _resolve_instance(_runtime(request), instance_id)
+    query = request.scope.get("query_string", b"")
+    suffix = f"?{query.decode('latin-1')}" if query else ""
+    return RedirectResponse(f"/atlas/{instance_id}/{suffix}", status_code=307)
+
+
+@router.api_route("/atlas/{instance_id}/{path:path}", methods=PROXY_METHODS, include_in_schema=False)
+async def proxy_atlas(instance_id: str, path: str, request: Request) -> StreamingResponse:
+    """Stream one HTTP request to a registered loopback Atlas process."""
+    del path  # Routing uses the decoded value; forwarding uses ASGI raw_path.
+    runtime = _runtime(request)
+    instance = _resolve_instance(runtime, instance_id)
+    upstream_url = _upstream_url(request, instance)
+    request_headers = _filtered_headers(request.headers.raw, private=PRIVATE_REQUEST_HEADERS)
+    content = request.stream() if request.method not in {"GET", "HEAD"} else None
+    upstream_request = runtime.proxy_client.build_request(
+        request.method,
+        upstream_url,
+        headers=request_headers,
+        content=content,
+    )
+    try:
+        upstream = await runtime.proxy_client.send(upstream_request, stream=True)
+    except httpx.TimeoutException as exc:
+        raise HTTPException(status_code=504, detail="Atlas did not respond before the proxy timeout") from exc
+    except (httpx.RequestError, AtlasRuntimeError) as exc:
+        raise HTTPException(status_code=502, detail="Atlas is not reachable through the local proxy") from exc
+
+    response_headers = _filtered_headers(upstream.headers.raw, private=PRIVATE_RESPONSE_HEADERS)
+    response_headers = [
+        (name, _rewrite_location(value, upstream_url=upstream_url, instance=instance) if name.lower() == b"location" else value)
+        for name, value in response_headers
+    ]
+    response_headers.append((b"referrer-policy", b"no-referrer"))
+    response = StreamingResponse(
+        _response_body(upstream),
+        status_code=upstream.status_code,
+        background=BackgroundTask(upstream.aclose),
+    )
+    response.raw_headers = response_headers
+    return response