atlas-chat 0.1.0__tar.gz

atlas_chat-0.1.0/.env.example

@@ -0,0 +1,253 @@
+#############################################
+# Core / Development
+#############################################
+# Development mode - skip authentication when true
+DEBUG_MODE=true
+
+#############################################
+# RAG Configuration
+# Enable RAG (Retrieval-Augmented Generation) feature
+# Configure RAG sources in config/overrides/rag-sources.json
+# See docs/admin/external-rag-api.md for configuration details
+#############################################
+FEATURE_RAG_ENABLED=false
+
+# RAG source secrets (referenced in rag-sources.json via ${ENV_VAR} syntax)
+# ATLAS_RAG_URL=https://your-atlas-rag-api.example.com
+# ATLAS_RAG_BEARER_TOKEN=your-api-key-here
+
+# Server configuration
+PORT=8000
+APP_NAME=ATLAS
+
+# Network binding configuration
+# ATLAS_HOST controls which network interface the server binds to
+# Default: 127.0.0.1 (localhost only, secure)
+# Set to 0.0.0.0 for production deployments that need external access
+# ATLAS_HOST=127.0.0.1
+
+# Authentication configuration
+# Header name to extract authenticated username from reverse proxy
+# Different reverse proxy setups use different header names (e.g., X-User-Email, X-Authenticated-User, X-Remote-User)
+# Default: X-User-Email
+# AUTH_USER_HEADER=X-User-Email
+
+# Proxy secret authentication (optional security layer)
+# When enabled, the reverse proxy must include a secret header to authenticate itself
+# This ensures the application only accepts requests from the trusted reverse proxy
+# FEATURE_PROXY_SECRET_ENABLED=false
+# PROXY_SECRET_HEADER=X-Proxy-Secret
+# PROXY_SECRET=your-secure-random-secret-here
+# AUTH_REDIRECT_URL=/a
+# API Keys for LLM services
+OPENAI_API_KEY=sk-pro
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+GOOGLE_API_KEY=your_google_api_key_here
+OPENROUTER_API_KEY=sk-or
+CEREBRAS_API_KEY=your_cerebras_api_key_here
+GROQ_API_KEY=your-groq_api_key_here
+
+
+# Banner system configuration
+BANNER_ENABLED=true
+
+
+# Example .env configuration for OpenTelemetry logging
+
+# Environment mode (development or production)
+ENVIRONMENT=development
+
+#############################################
+# UI / Frontend
+#############################################
+
+# Frontend build-time app name (Vite will inject this into index.html)
+VITE_APP_NAME=ATLAS
+
+# Frontend build-time flag to show the "Powered By Sandia ATLAS" badge
+# on the welcome screen. Other deployments can set this to false
+# to hide the badge while still customizing the main logo.
+VITE_FEATURE_POWERED_BY_ATLAS=false
+
+# OpenTelemetry configuration (optional - for future use)
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+# OTEL_SERVICE_NAME=atlas-ui-3-backend
+# OTEL_SERVICE_VERSION=1.0.0
+
+# Log level configuration (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+# Controls verbosity of application logs and sensitive data logging
+# - DEBUG: Verbose logging including user input/output content (for development/testing only)
+# - INFO: Standard logging with metrics and counts, but no sensitive content (recommended for production)
+# - WARNING/ERROR/CRITICAL: Minimal logging, errors and warnings only
+LOG_LEVEL=INFO
+
+# Metrics logging configuration
+# Enable tracking of user activities without capturing sensitive data
+# When enabled, logs contain only metadata (counts, sizes, types)
+# Excludes prompts, tool arguments, file names, and error details
+FEATURE_METRICS_LOGGING_ENABLED=false
+
+# Suppress LiteLLM verbose logging (independent of LOG_LEVEL)
+# When true, sets LITELLM_LOG=ERROR to silence LiteLLM's noisy stdout/debug output
+# When false, LiteLLM uses its default logging behavior
+FEATURE_SUPPRESS_LITELLM_LOGGING=true
+
+USE_NEW_FRONTEND=true
+
+#############################################
+# Feature Flags (rollout controls)
+# Toggle advanced capabilities without changing code.
+# Set to true to enable in UI + API; false hides & suppresses data.
+# These are initialized to reflect your current enabled features.
+#############################################
+# Workspace selector (none configured yet)
+FEATURE_WORKSPACES_ENABLED=false
+# Note: RAG is controlled by RAG_PROVIDER setting (see above)
+# MCP / tools panel
+FEATURE_TOOLS_ENABLED=true
+# Marketplace browsing (disabled)
+FEATURE_MARKETPLACE_ENABLED=true
+# Uploaded/session files panel
+FEATURE_FILES_PANEL_ENABLED=true
+# Previous chat history list
+FEATURE_CHAT_HISTORY_ENABLED=false
+# Compliance level filtering for MCP servers and data sources
+FEATURE_COMPLIANCE_LEVELS_ENABLED=false
+# Startup splash screen for displaying policies and information
+FEATURE_SPLASH_SCREEN_ENABLED=false
+# Restrict access to whitelisted email domains (config/defaults/domain-whitelist.json)
+FEATURE_DOMAIN_WHITELIST_ENABLED=false
+# Enable automatic reconnection to failed MCP servers with exponential backoff
+FEATURE_MCP_AUTO_RECONNECT_ENABLED=false
+# Enable automatic file content extraction for uploaded PDFs/images
+# Requires running the file extractor mock service: python mocks/file-extractor-mock/main.py
+FEATURE_FILE_CONTENT_EXTRACTION_ENABLED=false
+
+#############################################
+# File Content Extraction Service Configuration
+# These are optional - only needed when using external extraction services
+# The mock extractor service works without these credentials
+#############################################
+# PDF extractor service credentials (optional for mock service)
+# PDF_EXTRACTOR_API_KEY=your_pdf_extractor_api_key_here
+# PDF_EXTRACTOR_CLIENT_ID=your_pdf_extractor_client_id_here
+# Image vision extractor service credentials (optional for mock service)
+# IMAGE_EXTRACTOR_API_KEY=your_image_extractor_api_key_here
+# OCR extractor service credentials (optional for mock service)
+# OCR_EXTRACTOR_API_KEY=your_ocr_extractor_api_key_here
+
+# (Adjust above to stage rollouts. For a bare-bones chat set them all to false.)
+
+#############################################
+# MCP Auto-Reconnect Settings
+# These settings control the automatic reconnection behavior for failed MCP servers.
+# Only active when FEATURE_MCP_AUTO_RECONNECT_ENABLED=true
+#############################################
+# Base interval in seconds between reconnect attempts (default: 60)
+# MCP_RECONNECT_INTERVAL=60
+# Maximum interval in seconds (caps exponential backoff, default: 300)
+# MCP_RECONNECT_MAX_INTERVAL=300
+# Multiplier for exponential backoff (default: 2.0)
+# MCP_RECONNECT_BACKOFF_MULTIPLIER=2.0
+
+#############################################
+# MCP Timeouts
+# Timeout in seconds for MCP discovery calls - list_tools, list_prompts (default: 30)
+MCP_DISCOVERY_TIMEOUT=30
+# Timeout in seconds for MCP tool calls (default: 120)
+MCP_CALL_TIMEOUT=120
+#############################################
+
+#############################################
+# MCP Per-User Token Storage
+# Encryption key for storing user API keys/tokens for MCP servers
+# If not set, an ephemeral key is generated and tokens won't persist across restarts
+#############################################
+# MCP_TOKEN_ENCRYPTION_KEY=your-random-string-at-least-32-chars
+# Directory to store encrypted tokens (default: config/secure/)
+# MCP_TOKEN_STORAGE_DIR=config/secure
+
+#############################################
+# Configuration File Names
+# Override the default names for configuration files.
+# Useful for testing or managing multiple configurations.
+#############################################
+# Splash screen configuration file name
+# SPLASH_CONFIG_FILE=splash-config.json
+# MCP servers configuration file name
+# MCP_CONFIG_FILE=mcp.json
+# LLM models configuration file name
+# LLM_CONFIG_FILE=llmconfig.yml
+# Help page configuration file name
+# HELP_CONFIG_FILE=help-config.json
+
+
+# ths might be need for mcp serves to know where to download the files.
+# CHATUI_BACKEND_BASE_URL=http://127.0.0.1:8000
+
+#############################################
+# File Access for Remote MCP Servers
+#############################################
+# Public URL of the backend API for file downloads by remote MCP servers
+# This should be the publicly accessible URL (including protocol and port if non-standard)
+# Examples:
+#   - Production: https://atlas-ui.example.com
+#   - Development: http://localhost:8000
+#   - With non-standard port: https://atlas-ui.example.com:8443
+# If not set, relative URLs will be used (only works for local/stdio servers on the same machine)
+# BACKEND_PUBLIC_URL=https://atlas-ui.example.com
+
+# Whether to include base64 encoded file content as fallback in tool arguments
+# This allows MCP servers to access files even if they cannot reach the backend URL
+# WARNING: Enabling this can significantly increase message sizes for large files
+# Default: false (recommended - use URL-based access instead)
+# INCLUDE_FILE_CONTENT_BASE64=false
+
+
+# Agent mode configuration
+AGENT_MAX_STEPS=30
+AGENT_DEFAULT_ENABLED=true
+# Agent mode availability (renamed to align with other FEATURE_* flags)
+FEATURE_AGENT_MODE_AVAILABLE=true
+# Agent loop strategy: react (structured reasoning) or think-act (faster, concise)
+AGENT_LOOP_STRATEGY=think-act
+
+# Tool approval configuration
+# Require approval by default for all tools (can be overridden per-tool in mcp.json)
+REQUIRE_TOOL_APPROVAL_BY_DEFAULT=false
+# Force approval for all tools (admin-enforced) regardless of per-tool or default settings
+# Set to true to require approval for every tool call
+FORCE_TOOL_APPROVAL_GLOBALLY=false
+
+# APP_LOG_DIR defaults to <project_root>/logs when unset
+# APP_LOG_DIR=/path/to/logs
+
+CAPABILITY_TOKEN_SECRET=blablah
+
+#############################################
+# S3/MinIO Storage Configuration
+#############################################
+# Choose ONE option below (comment out the other)
+
+# --- Option 1: Mock S3 (Default - No Docker required) ---
+USE_MOCK_S3=true
+
+# --- Option 2: MinIO (Requires Docker) ---
+# Uncomment below and set USE_MOCK_S3=false to use MinIO
+# USE_MOCK_S3=false
+# S3_ENDPOINT=http://localhost:9000
+# # Must match bucket created in docker-compose.yml
+# S3_BUCKET_NAME=atlas-files
+# S3_ACCESS_KEY=minioadmin
+# S3_SECRET_KEY=minioadmin
+# S3_REGION=us-east-1
+# S3_TIMEOUT=30
+# S3_USE_SSL=false
+
+
+# Content Security Policy (CSP) configuration
+# IMPORTANT: To allow external URLs in iframes (for MCP tools that use iframe display),
+# add the URLs to the frame-src directive. Example:
+# SECURITY_CSP_VALUE="... frame-src 'self' blob: data: https://example.com https://dashboard.example.com; ..."
+# HERE the www.sandia.gov is added as an allowed iframe source.
+SECURITY_CSP_VALUE="default-src 'self'; img-src 'self' data: blob:; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; frame-src 'self' blob: data: https://www.sandia.gov; frame-ancestors 'self'"

atlas_chat-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: atlas-chat
+Version: 0.1.0
+Summary: Full-stack LLM chat interface with Model Context Protocol (MCP) integration
+Author: Sandia National Laboratories
+License: MIT
+Project-URL: Homepage, https://github.com/sandialabs/atlas
+Project-URL: Documentation, https://github.com/sandialabs/atlas/tree/main/docs
+Project-URL: Repository, https://github.com/sandialabs/atlas
+Project-URL: Issues, https://github.com/sandialabs/atlas/issues
+Keywords: llm,chat,mcp,ai,anthropic,openai,gemini
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: beautifulsoup4
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: bs4
+Requires-Dist: cryptography
+Requires-Dist: duckduckgo-search
+Requires-Dist: fastapi
+Requires-Dist: fastmcp>=2.10.0
+Requires-Dist: httpx
+Requires-Dist: litellm
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-exporter-otlp
+Requires-Dist: opentelemetry-instrumentation-fastapi
+Requires-Dist: opentelemetry-instrumentation-httpx
+Requires-Dist: opentelemetry-instrumentation-logging
+Requires-Dist: opentelemetry-sdk
+Requires-Dist: pandas
+Requires-Dist: pydantic
+Requires-Dist: PyJWT
+Requires-Dist: PyPDF2
+Requires-Dist: python-dotenv
+Requires-Dist: python-multipart
+Requires-Dist: python-pptx
+Requires-Dist: pyyaml
+Requires-Dist: reportlab
+Requires-Dist: requests
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: seaborn
+Requires-Dist: uvicorn[standard]
+Requires-Dist: websockets
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# Atlas UI 3
+
+[![CI/CD Pipeline](https://github.com/sandialabs/atlas-ui-3/actions/workflows/ci.yml/badge.svg)](https://github.com/sandialabs/atlas-ui-3/actions/workflows/ci.yml)
+[![Security Checks](https://github.com/sandialabs/atlas-ui-3/actions/workflows/security.yml/badge.svg)](https://github.com/sandialabs/atlas-ui-3/actions/workflows/security.yml)
+[![Docker Image](https://ghcr-badge.egpl.dev/sandialabs/atlas-ui-3/latest_tag?trim=major&label=latest)](https://github.com/sandialabs/atlas-ui-3/pkgs/container/atlas-ui-3)
+[![PyPI version](https://badge.fury.io/py/atlas-chat.svg)](https://badge.fury.io/py/atlas-chat)
+![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
+![React 19](https://img.shields.io/badge/react-19.2-blue.svg)
+![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+
+Atlas UI 3 is a secure chat application with MCP (Model Context Protocol) integration, developed by Sandia National Laboratories -- a U.S. Department of Energy national laboratory -- to support U.S. Government customers.
+
+
+
+![Screenshot](docs/readme_img/screenshot-11-6-2025image.png)
+
+## About the Project
+
+**Atlas UI 3** is a full-stack LLM chat interface that supports multiple AI models, including those from OpenAI, Anthropic, and Google. Its core feature is the integration with the Model Context Protocol (MCP), which allows the AI assistant to connect to external tools and data sources, enabling complex, real-time workflows.
+
+### Features
+
+*   **Multi-LLM Support**: Connect to various LLM providers.
+*   **MCP Integration**: Extend the AI's capabilities with custom tools.
+*   **RAG Support**: Enhance responses with Retrieval-Augmented Generation.
+*   **Secure and Configurable**: Features group-based access control, compliance levels, and a tool approval system.
+*   **Modern Stack**: Built with React 19, FastAPI, and WebSockets.
+*   **Python Package**: Install and use as a library or CLI tool.
+
+## Installation
+
+### Install from PyPI (Recommended for Users)
+
+```bash
+# Install the package
+pip install atlas-chat
+
+# Or with uv (faster)
+uv pip install atlas-chat
+```
+
+### CLI Usage
+
+After installation, three CLI tools are available:
+
+```bash
+# Set up configuration (run this first!)
+atlas-init              # Creates .env and config/ in current directory
+atlas-init --minimal    # Creates just a minimal .env file
+
+# Chat with an LLM
+atlas-chat "Hello, how are you?" --model gpt-4o
+atlas-chat "Use the search tool" --tools server_tool1
+atlas-chat --list-tools
+
+# Start the server
+atlas-server --port 8000
+atlas-server --env /path/to/.env --config-folder /path/to/config
+```
+
+### Python API Usage
+
+```python
+from atlas import AtlasClient, ChatResult
+
+# Async usage
+client = AtlasClient()
+result = await client.chat("Hello, how are you?")
+print(result.message)
+
+# With options
+result = await client.chat(
+    "Analyze this data",
+    model="gpt-4o",
+    selected_tools=["calculator", "search"],
+    agent_mode=True
+)
+
+# Sync wrapper
+result = client.chat_sync("Hello!")
+```
+
+## Quick Start (Development)
+
+### Prerequisites
+
+```bash
+# Install uv package manager (one-time)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv && source .venv/bin/activate
+uv pip install -r requirements.txt
+```
+
+### Development Installation (Editable Mode)
+
+For development, install the package in **editable mode**. This creates a link from your Python environment to your local source code, so any changes you make to the code are immediately available without reinstalling.
+
+```bash
+# Install in editable mode with uv (recommended)
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+**What editable mode gives you:**
+- Edit any Python file in `atlas/` and changes take effect immediately
+- CLI commands (`atlas-chat`, `atlas-server`) use your local code
+- Import `from atlas import AtlasClient` in scripts and get your local version
+- No need to reinstall after making changes
+
+**Example workflow:**
+```bash
+# Install once in editable mode
+uv pip install -e .
+
+# Edit code
+vim atlas/atlas_client.py
+
+# Run immediately with your changes - no reinstall needed
+atlas-chat "test my changes"
+python my_script.py  # uses updated AtlasClient
+```
+
+**Alternative: PYTHONPATH (if you can't use editable install)**
+```bash
+# Set PYTHONPATH manually when running
+PYTHONPATH=/path/to/atlas-ui-3 python atlas/main.py
+```
+
+### Running the Application
+
+**Linux/macOS:**
+```bash
+bash agent_start.sh
+```
+
+**Windows:**
+```powershell
+.\ps_agent_start.ps1
+```
+
+**Note for Windows users**: If you encounter frontend build errors related to Rollup dependencies, delete `frontend/package-lock.json` and `frontend/node_modules`, then run the script again.
+
+Both scripts automatically detect and work with Docker or Podman. The `agent_start.sh` script builds the frontend, starts necessary services, and launches the backend server.
+
+## Documentation
+
+We have created a set of comprehensive guides to help you get the most out of Atlas UI 3.
+
+*   **[Getting Started](./docs/getting-started/installation.md)**: The perfect starting point for all users. This guide covers how to get the application running with Docker or on your local machine.
+
+*   **[Administrator's Guide](./docs/admin/README.md)**: For those who will deploy and manage the application. This guide details configuration, security settings, access control, and other operational topics.
+
+*   **[Developer's Guide](./docs/developer/README.md)**: For developers who want to contribute to the project. It provides an overview of the architecture and instructions for creating new MCP servers.
+
+## Container Images
+
+Pre-built container images are available at `quay.io/agarlan-snl/atlas-ui-3:latest` (pushes automatically from main branch).
+
+## For AI Agent Contributors
+
+If you are an AI agent working on this repository, please refer to the following documents for the most current and concise guidance:
+
+*   **[CLAUDE.md](./CLAUDE.md)**: Detailed architecture, workflows, and conventions.
+*   **[GEMINI.md](./GEMINI.md)**: Gemini-specific instructions.
+*   **[.github/copilot-instructions.md](./.github/copilot-instructions.md)**: A compact guide for getting productive quickly.
+
+## License
+
+Copyright 2025 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software
+
+MIT License
+

atlas_chat-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Atlas UI 3
+
+[![CI/CD Pipeline](https://github.com/sandialabs/atlas-ui-3/actions/workflows/ci.yml/badge.svg)](https://github.com/sandialabs/atlas-ui-3/actions/workflows/ci.yml)
+[![Security Checks](https://github.com/sandialabs/atlas-ui-3/actions/workflows/security.yml/badge.svg)](https://github.com/sandialabs/atlas-ui-3/actions/workflows/security.yml)
+[![Docker Image](https://ghcr-badge.egpl.dev/sandialabs/atlas-ui-3/latest_tag?trim=major&label=latest)](https://github.com/sandialabs/atlas-ui-3/pkgs/container/atlas-ui-3)
+[![PyPI version](https://badge.fury.io/py/atlas-chat.svg)](https://badge.fury.io/py/atlas-chat)
+![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)
+![React 19](https://img.shields.io/badge/react-19.2-blue.svg)
+![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+
+Atlas UI 3 is a secure chat application with MCP (Model Context Protocol) integration, developed by Sandia National Laboratories -- a U.S. Department of Energy national laboratory -- to support U.S. Government customers.
+
+
+
+![Screenshot](docs/readme_img/screenshot-11-6-2025image.png)
+
+## About the Project
+
+**Atlas UI 3** is a full-stack LLM chat interface that supports multiple AI models, including those from OpenAI, Anthropic, and Google. Its core feature is the integration with the Model Context Protocol (MCP), which allows the AI assistant to connect to external tools and data sources, enabling complex, real-time workflows.
+
+### Features
+
+*   **Multi-LLM Support**: Connect to various LLM providers.
+*   **MCP Integration**: Extend the AI's capabilities with custom tools.
+*   **RAG Support**: Enhance responses with Retrieval-Augmented Generation.
+*   **Secure and Configurable**: Features group-based access control, compliance levels, and a tool approval system.
+*   **Modern Stack**: Built with React 19, FastAPI, and WebSockets.
+*   **Python Package**: Install and use as a library or CLI tool.
+
+## Installation
+
+### Install from PyPI (Recommended for Users)
+
+```bash
+# Install the package
+pip install atlas-chat
+
+# Or with uv (faster)
+uv pip install atlas-chat
+```
+
+### CLI Usage
+
+After installation, three CLI tools are available:
+
+```bash
+# Set up configuration (run this first!)
+atlas-init              # Creates .env and config/ in current directory
+atlas-init --minimal    # Creates just a minimal .env file
+
+# Chat with an LLM
+atlas-chat "Hello, how are you?" --model gpt-4o
+atlas-chat "Use the search tool" --tools server_tool1
+atlas-chat --list-tools
+
+# Start the server
+atlas-server --port 8000
+atlas-server --env /path/to/.env --config-folder /path/to/config
+```
+
+### Python API Usage
+
+```python
+from atlas import AtlasClient, ChatResult
+
+# Async usage
+client = AtlasClient()
+result = await client.chat("Hello, how are you?")
+print(result.message)
+
+# With options
+result = await client.chat(
+    "Analyze this data",
+    model="gpt-4o",
+    selected_tools=["calculator", "search"],
+    agent_mode=True
+)
+
+# Sync wrapper
+result = client.chat_sync("Hello!")
+```
+
+## Quick Start (Development)
+
+### Prerequisites
+
+```bash
+# Install uv package manager (one-time)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create virtual environment and install dependencies
+uv venv && source .venv/bin/activate
+uv pip install -r requirements.txt
+```
+
+### Development Installation (Editable Mode)
+
+For development, install the package in **editable mode**. This creates a link from your Python environment to your local source code, so any changes you make to the code are immediately available without reinstalling.
+
+```bash
+# Install in editable mode with uv (recommended)
+uv pip install -e .
+
+# Or with pip
+pip install -e .
+```
+
+**What editable mode gives you:**
+- Edit any Python file in `atlas/` and changes take effect immediately
+- CLI commands (`atlas-chat`, `atlas-server`) use your local code
+- Import `from atlas import AtlasClient` in scripts and get your local version
+- No need to reinstall after making changes
+
+**Example workflow:**
+```bash
+# Install once in editable mode
+uv pip install -e .
+
+# Edit code
+vim atlas/atlas_client.py
+
+# Run immediately with your changes - no reinstall needed
+atlas-chat "test my changes"
+python my_script.py  # uses updated AtlasClient
+```
+
+**Alternative: PYTHONPATH (if you can't use editable install)**
+```bash
+# Set PYTHONPATH manually when running
+PYTHONPATH=/path/to/atlas-ui-3 python atlas/main.py
+```
+
+### Running the Application
+
+**Linux/macOS:**
+```bash
+bash agent_start.sh
+```
+
+**Windows:**
+```powershell
+.\ps_agent_start.ps1
+```
+
+**Note for Windows users**: If you encounter frontend build errors related to Rollup dependencies, delete `frontend/package-lock.json` and `frontend/node_modules`, then run the script again.
+
+Both scripts automatically detect and work with Docker or Podman. The `agent_start.sh` script builds the frontend, starts necessary services, and launches the backend server.
+
+## Documentation
+
+We have created a set of comprehensive guides to help you get the most out of Atlas UI 3.
+
+*   **[Getting Started](./docs/getting-started/installation.md)**: The perfect starting point for all users. This guide covers how to get the application running with Docker or on your local machine.
+
+*   **[Administrator's Guide](./docs/admin/README.md)**: For those who will deploy and manage the application. This guide details configuration, security settings, access control, and other operational topics.
+
+*   **[Developer's Guide](./docs/developer/README.md)**: For developers who want to contribute to the project. It provides an overview of the architecture and instructions for creating new MCP servers.
+
+## Container Images
+
+Pre-built container images are available at `quay.io/agarlan-snl/atlas-ui-3:latest` (pushes automatically from main branch).
+
+## For AI Agent Contributors
+
+If you are an AI agent working on this repository, please refer to the following documents for the most current and concise guidance:
+
+*   **[CLAUDE.md](./CLAUDE.md)**: Detailed architecture, workflows, and conventions.
+*   **[GEMINI.md](./GEMINI.md)**: Gemini-specific instructions.
+*   **[.github/copilot-instructions.md](./.github/copilot-instructions.md)**: A compact guide for getting productive quickly.
+
+## License
+
+Copyright 2025 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software
+
+MIT License
+