Upload 83 files

backend/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db 
+
+# user-added
+instances/
+tavily_api.txt
+nvdev_api.txt
+mock_instances/
+logs/
+uvicorn_main.txt
+
+.DS_Store

backend/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to the Universal Deep Research Backend (UDR-B) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-07-15
+
+### Added
+
+- Initial release of Universal Deep Research Backend (UDR-B)
+- FastAPI-based REST API with streaming responses
+- Intelligent research capabilities using LLMs and web search
+- Multi-model support through compatible APIs (OpenAI, NVIDIA, local vLLM)
+- Tavily API integration for web search functionality
+- Session management with persistent research sessions
+- Advanced FrameV4 reasoning framework
+- Dry run mode for testing with mock data
+- Comprehensive configuration system with environment variables
+- Real-time progress updates via Server-Sent Events
+- CORS support for frontend integration
+- Logging and tracing capabilities
+- Mock data for development and testing
+
+### Technical Features
+
+- `/api/research` endpoint for comprehensive research workflow
+- `/api/research2` endpoint for advanced FrameV4-based research
+- Modular architecture with configurable components
+- Support for multiple LLM providers and models
+- Environment-based configuration management
+- Setup script for easy deployment
+- Comprehensive error handling and validation
+
+### Documentation
+
+- Complete README with setup and usage instructions
+- API endpoint documentation
+- Configuration guide
+- Troubleshooting section
+- Disclaimer for research/demonstration use
+
+### Research/Demonstration Focus
+
+- Prototype implementation for AI research concepts
+- Experimental features for academic research
+- Not intended for production use
+- Comprehensive legal disclaimer included
+
+---
+
+## Version History
+
+- **1.0.0**: Initial research prototype release

backend/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to Universal Deep Research
+
+This code details a research and demonstration prototype. This software is not intended for production use.
+
+## How to Contribute
+
+### 1. Fork and Clone
+
+```bash
+git clone <your-fork-url>
+cd backend
+```
+
+### 2. Set Up Development Environment
+
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### 3. Make Changes
+
+- Follow existing code style and patterns
+- Add tests for new functionality
+- Update documentation as needed
+- Ensure all TODO comments are addressed or documented
+
+### 4. Testing
+
+- Test API endpoints manually
+- Verify configuration changes work correctly
+
+### 5. Submit Pull Request
+
+- Create a descriptive PR title
+- Include clear description of changes
+- Ensure code follows research/demonstration focus
+
+## Code Standards
+
+- **Python**: Follow PEP 8 style guidelines
+- **Documentation**: Use clear docstrings and comments
+- **Error Handling**: Implement proper exception handling
+- **Configuration**: Use environment variables for customization
+- **Logging**: Use appropriate log levels and messages
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same terms as this project (research/demonstration use only). You can find the license in [LICENSE](LICENSE.txt).
+
+#### Signing Your Work
+
+- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
+
+  - Any contribution which contains commits that are not Signed-Off will not be accepted.
+
+- To sign off on a commit you simply use the `--signoff` (or `-s`) option when committing your changes:
+
+  ```bash
+  $ git commit -s -m "Add cool feature."
+  ```
+
+  This will append the following to your commit message:
+
+  ```
+  Signed-off-by: Your Name <[email protected]>
+  ```
+
+- Full text of the DCO:
+
+  ```
+    Developer Certificate of Origin
+    Version 1.1
+
+    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+    1 Letterman Drive
+    Suite D4700
+    San Francisco, CA, 94129
+
+    Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+  ```
+
+  ```
+    Developer's Certificate of Origin 1.1
+
+    By making a contribution to this project, I certify that:
+
+    (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
+
+    (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
+
+    (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
+
+    (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
+  ```

backend/DISCLAIMER.txt

@@ -0,0 +1,35 @@
+DISCLAIMER
+
+IMPORTANT NOTICE - RESEARCH DEMONSTRATION PROTOTYPE
+
+This software and all associated code, documentation, and materials (collectively, the "Software") are provided solely for research and demonstration purposes. The Software is intended exclusively as a prototype to demonstrate research concepts and methodologies in the field of artificial intelligence and automated research systems.
+
+CRITICAL LIMITATIONS AND WARNINGS:
+
+1. RESEARCH PURPOSE ONLY: The Software is designed and intended solely for academic research, educational demonstration, and experimental purposes. It is NOT intended for production use, commercial deployment, or any real-world application.
+
+2. NO PRODUCTION USE: Under no circumstances should this Software be deployed, used, or relied upon in any production environment, commercial application, or any context where reliability, accuracy, or safety is required.
+
+3. EXPERIMENTAL NATURE: The Software contains experimental features, unproven methodologies, and research-grade implementations that may contain bugs, security vulnerabilities, or other issues that could cause data loss, system instability, or other problems.
+
+4. NO WARRANTIES: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR ACCURACY.
+
+5. NO LIABILITY: TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, NEITHER NVIDIA CORPORATION, NOR THE AUTHORS, CONTRIBUTORS, OR ANY OTHER PARTIES INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THE SOFTWARE SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. NO SUPPORT: No technical support, maintenance, updates, or assistance is provided for this Software. Users are solely responsible for their use of the Software and any consequences thereof.
+
+7. NO ENDORSEMENT: The inclusion of any third-party components, APIs, or services does not constitute an endorsement of those services or their providers.
+
+8. COMPLIANCE: Users are responsible for ensuring their use of the Software complies with all applicable laws, regulations, and terms of service for any third-party services or APIs used by the Software.
+
+9. SECURITY: The Software has not been subjected to security audits or testing suitable for production environments. Users assume all risks associated with security vulnerabilities.
+
+10. DATA PRIVACY: The Software may process, transmit, or store data in ways that do not comply with data protection regulations. Users are responsible for ensuring compliance with applicable privacy laws.
+
+ACKNOWLEDGMENT:
+
+By using, copying, modifying, or distributing the Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this disclaimer. If you do not agree to these terms, you must not use the Software.
+
+For questions regarding this disclaimer, please contact the authors through the appropriate channels established for this research project.
+
+Last updated: 07/15/2025.

backend/README.md

@@ -0,0 +1,406 @@
+# Universal Deep Research Backend (UDR-B)
+
+A FastAPI-based backend service that provides intelligent research and reporting capabilities using large language models and web search APIs. The system can perform comprehensive research on user queries, aggregate findings, and generate detailed reports.
+
+This software is provided exclusively for research and demonstration purposes. It is intended solely as a prototype to demonstrate research concepts and methodologies in artificial intelligence and automated research systems.
+
+- This software is not intended for production deployment, commercial use, or any real-world application where reliability, accuracy, or safety is required.
+- This software contains experimental features, unproven methodologies, and research-grade implementations that may contain bugs, security vulnerabilities, or other issues.
+- The software is provided "AS IS" without any warranties. Neither NVIDIA Corporation nor the authors shall be liable for any damages arising from the use of this software to the fullest extent permitted by law.
+
+By using this software, you acknowledge that you have read and understood the complete DISCLAIMER file and agree to be bound by its terms. For the complete legal disclaimer, please see the [DISCLAIMER](DISCLAIMER.txt) file in this directory.
+
+## Features
+
+- **Intelligent Research**: Automated web search and content analysis using Tavily API
+- **Multi-Model Support**: Configurable LLM backends (OpenAI, NVIDIA, local vLLM)
+- **Streaming Responses**: Real-time progress updates via Server-Sent Events
+- **Session Management**: Persistent research sessions with unique identifiers
+- **Flexible Architecture**: Modular design with configurable components
+- **Dry Run Mode**: Testing capabilities with mock data
+- **Advanced Framing**: Custom FrameV4 system for increased reliability of instruction following across all models
+
+## Architecture
+
+The backend consists of several key components:
+
+- **`main.py`**: FastAPI application with research endpoints
+- **`scan_research.py`**: Core research and reporting logic
+- **`clients.py`**: LLM and search API client management
+- **`frame/`**: Advanced reliability framework (FrameV4)
+- **`items.py`**: Data persistence utilities
+- **`sessions.py`**: Session key generation and management
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.8+
+- API keys for your chosen LLM provider
+- Tavily API key for web search functionality
+
+### Installation
+
+#### Option 1: Automated Setup (Recommended)
+
+The easiest way to set up the backend is using the provided `setup.py` script:
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone <repository-url>
+   cd backend
+   ```
+
+2. **Run the setup script**:
+
+   ```bash
+   python3 setup.py
+   ```
+
+   The setup script will:
+
+   - Check Python version compatibility
+   - Create necessary directories (`logs/`, `instances/`, `mock_instances/`)
+   - Set up environment configuration (`.env` file)
+   - Check for required API key files
+   - Install Python dependencies
+   - Validate the setup
+
+3. **Configure API keys**:
+   Create the following files with your API keys:
+
+   ```bash
+   echo "your-tavily-api-key" > tavily_api.txt
+   echo "your-llm-api-key" > nvdev_api.txt  # or openai_api.txt
+   ```
+
+4. **Start the server**:
+
+   ```bash
+   ./launch_server.sh
+   ```
+
+   **Note**: The `launch_server.sh` script is the recommended way to start the server as it:
+
+   - Automatically loads environment variables from `.env`
+   - Sets proper default configurations
+   - Runs the server in the background with logging
+   - Provides process management information
+
+#### Option 2: Manual Setup
+
+If you prefer to set up the backend manually, follow these steps:
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone <repository-url>
+   cd backend
+   ```
+
+2. **Create virtual environment**:
+
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install dependencies**:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Create necessary directories**:
+
+   ```bash
+   mkdir -p logs instances mock_instances
+   ```
+
+5. **Set up environment configuration**:
+   Copy the example environment file and configure it:
+
+   ```bash
+   cp env.example .env
+   # Edit .env file with your configuration
+   ```
+
+6. **Configure API keys**:
+   Create the following files with your API keys:
+
+   ```bash
+   echo "your-tavily-api-key" > tavily_api.txt
+   echo "your-llm-api-key" > nvdev_api.txt  # or e.g., openai_api.txt
+   ```
+
+7. **Start the server**:
+
+   ```bash
+   ./launch_server.sh
+   ```
+
+   **Note**: As noted for Option 1, the `launch_server.sh` script is the recommended way to start the server as it:
+
+   - Automatically loads environment variables from `.env`
+   - Sets proper default configurations
+   - Runs the server in the background with logging
+   - Provides process management information
+
+The server will be available at `http://localhost:8000`
+
+You can now quickly test the server.
+
+```bash
+curl -X POST http://localhost:8000/api/research \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "What are the latest developments in quantum computing?",
+    "start_from": "research"
+  }'
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the backend directory:
+
+```env
+# Server Configuration
+HOST=0.0.0.0
+PORT=8000
+LOG_LEVEL=info
+
+# CORS Configuration
+FRONTEND_URL=http://localhost:3000
+
+# Model Configuration
+DEFAULT_MODEL=llama-3.1-nemotron-253b
+LLM_BASE_URL=https://integrate.api.nvidia.com/v1
+LLM_API_KEY_FILE=nvdev_api.txt
+
+# Search Configuration
+TAVILY_API_KEY_FILE=tavily_api.txt
+
+# Research Configuration
+MAX_TOPICS=1
+MAX_SEARCH_PHRASES=1
+MOCK_DIRECTORY=mock_instances/stocks_24th_3_sections
+
+# Logging Configuration
+LOG_DIR=logs
+TRACE_ENABLED=true
+```
+
+### Model Configuration
+
+The system supports multiple LLM providers. Configure models in `clients.py`:
+
+```python
+MODEL_CONFIGS = {
+    "llama-3.1-8b": {
+        "base_url": "https://integrate.api.nvidia.com/v1",
+        "api_type": "nvdev",
+        "completion_config": {
+            "model": "nvdev/meta/llama-3.1-8b-instruct",
+            "temperature": 0.2,
+            "top_p": 0.7,
+            "max_tokens": 2048,
+            "stream": True
+        }
+    },
+    # Add more models as needed
+}
+```
+
+### API Key Files
+
+The system expects API keys in text files:
+
+- `tavily_api.txt`: Tavily search API key
+- `nvdev_api.txt`: NVIDIA API key
+- `openai_api.txt`: OpenAI API key
+
+## API Endpoints
+
+### GET `/`
+
+Health check endpoint that returns a status message.
+
+### POST `/api/research`
+
+Main research endpoint that performs research and generates reports.
+
+**Request Body**:
+
+```json
+{
+  "dry": false,
+  "session_key": "optional-session-key",
+  "start_from": "research",
+  "prompt": "Your research query here",
+  "mock_directory": "mock_instances/stocks_24th_3_sections"
+}
+```
+
+**Parameters**:
+
+- `dry` (boolean): Use mock data for testing
+- `session_key` (string, optional): Existing session to continue
+- `start_from` (string): "research" or "reporting"
+- `prompt` (string): Research query (required for research phase)
+- `mock_directory` (string): Directory for mock data
+
+**Response**: Server-Sent Events stream with research progress
+
+### POST `/api/research2`
+
+Advanced reliability framework endpoint using FrameV4 system. This is the endpoint that supports custom user deep research strategies.
+
+**Request Body**:
+
+```json
+{
+  "prompt": "Your research query",
+  "strategy_id": "custom-strategy",
+  "strategy_content": "Custom research strategy"
+}
+```
+
+## Usage Examples
+
+### Basic Research Request
+
+```bash
+curl -X POST http://localhost:8000/api/research \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "What are the latest developments in quantum computing?",
+    "start_from": "research"
+  }'
+```
+
+### Dry Run Testing
+
+```bash
+curl -X POST http://localhost:8000/api/research \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dry": true,
+    "prompt": "Test research query",
+    "start_from": "research"
+  }'
+```
+
+### Continue from Reporting Phase
+
+```bash
+curl -X POST http://localhost:8000/api/research \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_key": "20241201T120000Z-abc12345", # This would be the key of the session which you have previously started
+    "start_from": "reporting"
+  }'
+```
+
+## Development
+
+### Logging
+
+Logs are stored in the `logs/` directory:
+
+- `comms_YYYYMMDD_HH-MM-SS.log`: Communication traces
+- `{instance_id}_compilation.log`: Frame compilation logs
+- `{instance_id}_execution.log`: Frame execution logs
+
+### Mock Data
+
+Mock research data is available in `mock_instances/`:
+
+- `stocks_24th_3_sections/`: Stock market research data
+- `stocks_30th_short/`: Short stock market data
+
+## Deployment
+
+### Production Deployment
+
+1. **Set up environment**:
+
+   ```bash
+   export HOST=0.0.0.0
+   export PORT=8000
+   export LOG_LEVEL=info
+   ```
+
+2. **Run with gunicorn**:
+
+   ```bash
+   pip install gunicorn
+   gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+   ```
+
+   **Note**: For development, prefer using `./launch_server.sh` which provides better process management and logging.
+
+### Docker Deployment
+
+Create a `Dockerfile`:
+
+```dockerfile
+FROM python:3.9-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+EXPOSE 8000
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **API Key Errors**: Ensure API key files exist and contain valid keys
+2. **CORS Errors**: Check `FRONTEND_URL` configuration
+3. **Model Errors**: Verify model configuration in `clients.py`
+4. **Permission Errors**: Ensure write permissions for `logs/` and `instances/` directories
+
+### Debug Mode
+
+Enable debug logging by setting the LOG_LEVEL environment variable:
+
+```bash
+export LOG_LEVEL=debug
+./launch_server.sh
+```
+
+Or run uvicorn directly for debugging:
+
+```bash
+uvicorn main:app --reload --log-level=debug
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License and Disclaimer
+
+This software is provided for research and demonstration purposes only. Please refer to the [DISCLAIMER](DISCLAIMER.txt) file for complete terms and conditions regarding the use of this software. You can find the license in [LICENSE](LICENSE.txt).
+
+**Do not use this code in production.**
+
+## Support
+
+For issues and questions:
+
+- Create an issue in the repository
+- Check the logs in the `logs/` directory
+- Review the configuration settings

backend/clients.py

@@ -0,0 +1,249 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Client management module for LLM and search API interactions.
+
+This module provides client creation and management for:
+- Large Language Models (OpenAI, NVIDIA, local vLLM)
+- Web search (Tavily API)
+- Configuration-based client setup
+"""
+
+from typing import Any, Dict, List, Literal, TypedDict
+
+from openai import OpenAI
+from tavily import TavilyClient
+
+from config import get_config
+
+# Get configuration
+config = get_config()
+
+# Configuration system
+ApiType = Literal["nvdev", "openai", "tavily"]
+
+
+class ModelConfig(TypedDict):
+    base_url: str
+    api_type: ApiType
+    completion_config: Dict[str, Any]
+
+
+# Available model configurations
+MODEL_CONFIGS: Dict[str, ModelConfig] = {
+    "llama-3.1-8b": {
+        "base_url": "https://integrate.api.nvidia.com/v1",
+        "api_type": "nvdev",
+        "completion_config": {
+            "model": "nvdev/meta/llama-3.1-8b-instruct",
+            "temperature": 0.2,
+            "top_p": 0.7,
+            "max_tokens": 2048,
+            "stream": True,
+        },
+    },
+    "llama-3.1-nemotron-8b": {
+        "base_url": "https://integrate.api.nvidia.com/v1",
+        "api_type": "nvdev",
+        "completion_config": {
+            "model": "nvdev/nvidia/llama-3.1-nemotron-nano-8b-v1",
+            "temperature": 0.2,
+            "top_p": 0.7,
+            "max_tokens": 2048,
+            "stream": True,
+        },
+    },
+    "llama-3.1-nemotron-253b": {
+        "base_url": "https://integrate.api.nvidia.com/v1",
+        "api_type": "nvdev",
+        "completion_config": {
+            "model": "nvdev/nvidia/llama-3.1-nemotron-ultra-253b-v1",
+            "temperature": 0.2,
+            "top_p": 0.7,
+            "max_tokens": 2048,
+            "stream": True,
+        },
+    },
+}
+
+# Default model to use (from configuration)
+DEFAULT_MODEL = config.model.default_model
+
+
+def get_api_key(api_type: ApiType) -> str:
+    """
+    Get the API key for the specified API type.
+
+    This function reads API keys from configuration-specified files.
+    The file paths can be customized via environment variables.
+
+    Args:
+        api_type: The type of API to get the key for ("nvdev", "openai", "tavily")
+
+    Returns:
+        str: The API key from the configured file
+
+    Raises:
+        FileNotFoundError: If the API key file doesn't exist
+        ValueError: If the API type is unknown
+
+    Example:
+        >>> get_api_key("tavily")
+        "your-tavily-api-key"
+    """
+    api_key_files = {
+        "nvdev": config.model.api_key_file,
+        "openai": "openai_api.txt",
+        "tavily": config.search.tavily_api_key_file,
+    }
+
+    key_file = api_key_files.get(api_type)
+    if not key_file:
+        raise ValueError(f"Unknown API type: {api_type}")
+
+    try:
+        with open(key_file, "r") as file:
+            return file.read().strip()
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"API key file not found for {api_type}. "
+            f"Please create {key_file} with your API key. "
+            f"See README.md for configuration instructions."
+        )
+
+
+def create_lm_client(model_config: ModelConfig | None = None) -> OpenAI:
+    """
+    Create an OpenAI client instance with the specified configuration.
+
+    This function creates a client for the configured LLM provider.
+    The client can be customized with specific model configurations
+    or will use the default model from configuration.
+
+    Args:
+        model_config: Optional model configuration to override defaults.
+                     If None, uses the default model from configuration.
+
+    Returns:
+        OpenAI: Configured OpenAI client instance
+
+    Example:
+        >>> client = create_lm_client()
+        >>> response = client.chat.completions.create(...)
+    """
+    model_config = model_config or MODEL_CONFIGS[DEFAULT_MODEL]
+    api_key = get_api_key(model_config["api_type"])
+
+    return OpenAI(base_url=model_config["base_url"], api_key=api_key)
+
+
+def create_tavily_client() -> TavilyClient:
+    """
+    Create a Tavily client instance for web search functionality.
+
+    This function creates a client for the Tavily search API using
+    the API key from the configured file path.
+
+    Returns:
+        TavilyClient: Configured Tavily client instance
+
+    Raises:
+        FileNotFoundError: If the Tavily API key file is not found
+
+    Example:
+        >>> client = create_tavily_client()
+        >>> results = client.search("quantum computing")
+    """
+    api_key = get_api_key("tavily")
+    return TavilyClient(api_key=api_key)
+
+
+def get_completion(
+    client: OpenAI,
+    messages: List[Dict[str, Any]],
+    model_config: ModelConfig | None = None,
+) -> str:
+    """
+    Get completion from the OpenAI client using the specified model configuration.
+
+    This function handles both streaming and non-streaming completions,
+    with special handling for certain model configurations that require
+    specific message formatting.
+
+    Args:
+        client: OpenAI client instance
+        messages: List of messages for the completion
+        model_config: Optional model configuration to override defaults.
+                     If None, uses the default model configuration.
+
+    Returns:
+        str: The completion text
+
+    Example:
+        >>> client = create_lm_client()
+        >>> messages = [{"role": "user", "content": "Hello"}]
+        >>> response = get_completion(client, messages)
+        >>> print(response)
+        "Hello! How can I help you today?"
+    """
+    model_config = model_config or MODEL_CONFIGS[DEFAULT_MODEL]
+
+    # Handle special model configurations
+    if "retarded" in model_config and model_config["retarded"]:
+        if messages[0]["role"] == "system":
+            first_message = messages[0]
+            messages = [msg for msg in messages if msg["role"] != "system"]
+            messages[0]["content"] = (
+                first_message["content"] + "\n\n" + messages[0]["content"]
+            )
+            messages.insert(0, {"role": "system", "content": "detailed thinking off"})
+
+    completion = client.chat.completions.create(
+        messages=messages, **model_config["completion_config"]
+    )
+
+    # Handle streaming vs non-streaming responses
+    if model_config["completion_config"]["stream"]:
+        ret = ""
+        for chunk in completion:
+            if chunk.choices[0].delta.content:
+                ret += chunk.choices[0].delta.content
+    else:
+        ret = completion.choices[0].message.content
+
+    return ret
+
+
+def is_output_positive(output: str) -> bool:
+    """
+    Check if the output contains positive indicators.
+
+    This function checks if the given output string contains
+    positive words like "yes" or "true" (case-insensitive).
+
+    Args:
+        output: The string to check for positive indicators
+
+    Returns:
+        bool: True if positive indicators are found, False otherwise
+
+    Example:
+        >>> is_output_positive("Yes, that's correct")
+        True
+        >>> is_output_positive("No, that's not right")
+        False
+    """
+    positive_words = ["yes", "true"]
+    return any(word in output.lower() for word in positive_words)

backend/config.py

@@ -0,0 +1,262 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Configuration module for the Universal Deep Research Backend (UDR-B).
+
+This module centralizes all configurable settings and provides
+environment variable support for easy deployment customization.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+@dataclass
+class ServerConfig:
+    """Server configuration settings."""
+
+    host: str = field(default_factory=lambda: os.getenv("HOST", "0.0.0.0"))
+    port: int = field(default_factory=lambda: int(os.getenv("PORT", "8000")))
+    log_level: str = field(default_factory=lambda: os.getenv("LOG_LEVEL", "info"))
+    reload: bool = field(
+        default_factory=lambda: os.getenv("RELOAD", "true").lower() == "true"
+    )
+
+
+@dataclass
+class CORSConfig:
+    """CORS configuration settings."""
+
+    frontend_url: str = field(
+        default_factory=lambda: os.getenv("FRONTEND_URL", "http://localhost:3000")
+    )
+    allow_credentials: bool = field(
+        default_factory=lambda: os.getenv("ALLOW_CREDENTIALS", "true").lower() == "true"
+    )
+    allow_methods: list = field(default_factory=lambda: ["*"])
+    allow_headers: list = field(default_factory=lambda: ["*"])
+
+
+@dataclass
+class ModelConfig:
+    """Model configuration settings."""
+
+    default_model: str = field(
+        default_factory=lambda: os.getenv("DEFAULT_MODEL", "llama-3.1-nemotron-253b")
+    )
+    base_url: str = field(
+        default_factory=lambda: os.getenv(
+            "LLM_BASE_URL", "https://integrate.api.nvidia.com/v1"
+        )
+    )
+    api_key_file: str = field(
+        default_factory=lambda: os.getenv("LLM_API_KEY_FILE", "nvdev_api.txt")
+    )
+    temperature: float = field(
+        default_factory=lambda: float(os.getenv("LLM_TEMPERATURE", "0.2"))
+    )
+    top_p: float = field(default_factory=lambda: float(os.getenv("LLM_TOP_P", "0.7")))
+    max_tokens: int = field(
+        default_factory=lambda: int(os.getenv("LLM_MAX_TOKENS", "2048"))
+    )
+
+
+@dataclass
+class SearchConfig:
+    """Search configuration settings."""
+
+    tavily_api_key_file: str = field(
+        default_factory=lambda: os.getenv("TAVILY_API_KEY_FILE", "tavily_api.txt")
+    )
+    max_search_results: int = field(
+        default_factory=lambda: int(os.getenv("MAX_SEARCH_RESULTS", "10"))
+    )
+
+
+@dataclass
+class ResearchConfig:
+    """Research configuration settings."""
+
+    max_topics: int = field(default_factory=lambda: int(os.getenv("MAX_TOPICS", "1")))
+    max_search_phrases: int = field(
+        default_factory=lambda: int(os.getenv("MAX_SEARCH_PHRASES", "1"))
+    )
+    mock_directory: str = field(
+        default_factory=lambda: os.getenv(
+            "MOCK_DIRECTORY", "mock_instances/stocks_24th_3_sections"
+        )
+    )
+    random_seed: int = field(
+        default_factory=lambda: int(os.getenv("RANDOM_SEED", "42"))
+    )
+
+
+@dataclass
+class LoggingConfig:
+    """Logging configuration settings."""
+
+    log_dir: str = field(default_factory=lambda: os.getenv("LOG_DIR", "logs"))
+    trace_enabled: bool = field(
+        default_factory=lambda: os.getenv("TRACE_ENABLED", "true").lower() == "true"
+    )
+    copy_into_stdout: bool = field(
+        default_factory=lambda: os.getenv("COPY_INTO_STDOUT", "false").lower() == "true"
+    )
+
+
+@dataclass
+class FrameConfig:
+    """FrameV4 configuration settings."""
+
+    long_context_cutoff: int = field(
+        default_factory=lambda: int(os.getenv("LONG_CONTEXT_CUTOFF", "8192"))
+    )
+    force_long_context: bool = field(
+        default_factory=lambda: os.getenv("FORCE_LONG_CONTEXT", "false").lower()
+        == "true"
+    )
+    max_iterations: int = field(
+        default_factory=lambda: int(os.getenv("MAX_ITERATIONS", "1024"))
+    )
+    interaction_level: str = field(
+        default_factory=lambda: os.getenv("INTERACTION_LEVEL", "none")
+    )
+
+
+@dataclass
+class AppConfig:
+    """Main application configuration."""
+
+    server: ServerConfig = field(default_factory=ServerConfig)
+    cors: CORSConfig = field(default_factory=CORSConfig)
+    model: ModelConfig = field(default_factory=ModelConfig)
+    search: SearchConfig = field(default_factory=SearchConfig)
+    research: ResearchConfig = field(default_factory=ResearchConfig)
+    logging: LoggingConfig = field(default_factory=LoggingConfig)
+    frame: FrameConfig = field(default_factory=FrameConfig)
+
+    def __post_init__(self):
+        """Ensure log directory exists."""
+        os.makedirs(self.logging.log_dir, exist_ok=True)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        return {
+            "server": {
+                "host": self.server.host,
+                "port": self.server.port,
+                "log_level": self.server.log_level,
+                "reload": self.server.reload,
+            },
+            "cors": {
+                "frontend_url": self.cors.frontend_url,
+                "allow_credentials": self.cors.allow_credentials,
+                "allow_methods": self.cors.allow_methods,
+                "allow_headers": self.cors.allow_headers,
+            },
+            "model": {
+                "default_model": self.model.default_model,
+                "base_url": self.model.base_url,
+                "api_key_file": self.model.api_key_file,
+                "temperature": self.model.temperature,
+                "top_p": self.model.top_p,
+                "max_tokens": self.model.max_tokens,
+            },
+            "search": {
+                "tavily_api_key_file": self.search.tavily_api_key_file,
+                "max_search_results": self.search.max_search_results,
+            },
+            "research": {
+                "max_topics": self.research.max_topics,
+                "max_search_phrases": self.research.max_search_phrases,
+                "mock_directory": self.research.mock_directory,
+                "random_seed": self.research.random_seed,
+            },
+            "logging": {
+                "log_dir": self.logging.log_dir,
+                "trace_enabled": self.logging.trace_enabled,
+                "copy_into_stdout": self.logging.copy_into_stdout,
+            },
+            "frame": {
+                "long_context_cutoff": self.frame.long_context_cutoff,
+                "force_long_context": self.frame.force_long_context,
+                "max_iterations": self.frame.max_iterations,
+                "interaction_level": self.frame.interaction_level,
+            },
+        }
+
+
+# Global configuration instance
+config = AppConfig()
+
+
+def get_config() -> AppConfig:
+    """Get the global configuration instance."""
+    return config
+
+
+def update_config(**kwargs) -> None:
+    """Update configuration with new values."""
+    for key, value in kwargs.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+        else:
+            raise ValueError(f"Unknown configuration key: {key}")
+
+
+def get_model_configs() -> Dict[str, Dict[str, Any]]:
+    """Get the model configurations from clients.py with configurable values."""
+    from clients import MODEL_CONFIGS
+
+    # Update model configs with environment variables
+    updated_configs = {}
+    for model_name, model_config in MODEL_CONFIGS.items():
+        updated_config = model_config.copy()
+
+        # Override with environment variables if available
+        env_prefix = f"{model_name.upper().replace('-', '_')}_"
+
+        if os.getenv(f"{env_prefix}BASE_URL"):
+            updated_config["base_url"] = os.getenv(f"{env_prefix}BASE_URL")
+
+        if os.getenv(f"{env_prefix}MODEL"):
+            updated_config["completion_config"]["model"] = os.getenv(
+                f"{env_prefix}MODEL"
+            )
+
+        if os.getenv(f"{env_prefix}TEMPERATURE"):
+            updated_config["completion_config"]["temperature"] = float(
+                os.getenv(f"{env_prefix}TEMPERATURE")
+            )
+
+        if os.getenv(f"{env_prefix}TOP_P"):
+            updated_config["completion_config"]["top_p"] = float(
+                os.getenv(f"{env_prefix}TOP_P")
+            )
+
+        if os.getenv(f"{env_prefix}MAX_TOKENS"):
+            updated_config["completion_config"]["max_tokens"] = int(
+                os.getenv(f"{env_prefix}MAX_TOKENS")
+            )
+
+        updated_configs[model_name] = updated_config
+
+    return updated_configs

backend/env.example

@@ -0,0 +1,47 @@
+# Universal Deep Research Backend (UDR-B) - Environment Configuration
+# Copy this file to .env and customize the values for your deployment
+
+# Server Configuration
+HOST=0.0.0.0
+PORT=8000
+LOG_LEVEL=info
+
+# CORS Configuration
+FRONTEND_URL=http://localhost:3000
+ALLOW_CREDENTIALS=true
+
+# Model Configuration
+DEFAULT_MODEL=llama-3.1-nemotron-253b
+LLM_BASE_URL=https://integrate.api.nvidia.com/v1
+LLM_API_KEY_FILE=nvdev_api.txt
+LLM_TEMPERATURE=0.2
+LLM_TOP_P=0.7
+LLM_MAX_TOKENS=2048
+
+# Search Configuration
+TAVILY_API_KEY_FILE=tavily_api.txt
+MAX_SEARCH_RESULTS=10
+
+# Research Configuration
+MAX_TOPICS=1
+MAX_SEARCH_PHRASES=1
+MOCK_DIRECTORY=mock_instances/stocks_24th_3_sections
+RANDOM_SEED=42
+
+# Logging Configuration
+LOG_DIR=logs
+TRACE_ENABLED=true
+COPY_INTO_STDOUT=false
+
+# FrameV4 Configuration
+LONG_CONTEXT_CUTOFF=8192
+FORCE_LONG_CONTEXT=false
+MAX_ITERATIONS=1024
+INTERACTION_LEVEL=none
+
+# Model-specific overrides (optional)
+# LLAMA_3_1_8B_BASE_URL=https://integrate.api.nvidia.com/v1
+# LLAMA_3_1_8B_MODEL=nvdev/meta/llama-3.1-8b-instruct
+# LLAMA_3_1_8B_TEMPERATURE=0.2
+# LLAMA_3_1_8B_TOP_P=0.7
+# LLAMA_3_1_8B_MAX_TOKENS=2048 

backend/frame/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

backend/frame/clients.py

@@ -0,0 +1,221 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .trace import Trace
+
+
+class Client:
+    def __init__(self, trace: Trace = None) -> None:
+        self.trace = trace
+
+    def run(self, pre_prompt: str, prompt: str, completion_config: dict = {}) -> str:
+        self.trace_query(pre_prompt, prompt, completion_config)
+
+    def run_messages(
+        self,
+        messages: list[dict],
+        trace_input_messages: bool = True,
+        completion_config: dict = {},
+    ) -> list[dict]:
+        if trace_input_messages:
+            self.trace.write_separator()
+            for message in messages:
+                self.trace_message(message)
+
+    def trace_message(self, message: dict) -> str:
+        if self.trace is not None:
+            self.trace(f"<<{message['role']}>>")
+            self.trace(message["content"])
+
+    def trace_query(
+        self, pre_prompt: str, prompt: str, completion_config: dict = {}
+    ) -> str:
+        if self.trace is not None:
+            self.trace.write_separator()
+            self.trace("<<PRE-PROMPT>>")
+            self.trace(pre_prompt)
+            self.trace("<<PROMPT>>")
+            self.trace(prompt)
+
+    def trace_response(self, response: str) -> str:
+        if self.trace is not None:
+            self.trace("<<RESPONSE>>")
+            self.trace(response)
+
+
+class HuggingFaceClient(Client):
+    def __init__(
+        self,
+        model: str = None,
+        pipeline_configuration: dict = {},
+        seed: int = 42,
+        api_key: str | None = None,
+        trace: Trace = None,
+    ) -> None:
+        super().__init__(trace=trace)
+
+        # to decrease the chance of hard-to-track bugs, we don't allow the 'model' key in pipeline_configuration
+        if "model" in pipeline_configuration:
+            raise ValueError(
+                "The 'model' key is not allowed in pipeline_configuration. Use the 'model' parameter instead."
+            )
+
+        # data members
+        self.model = model
+        self.seed = seed
+        if api_key is None:
+            import os
+
+            self.api_key = os.getenv("HUGGINGFACE_API_KEY")
+        self.api_key = api_key
+
+        # complete pipeline config
+        from transformers import pipeline
+
+        default_configuration = {
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "device": "cuda:0",
+            "max_new_tokens": 1024,
+        }
+        merged_configuration = {**default_configuration, **pipeline_configuration}
+
+        # model
+        if self.model is not None:
+            merged_configuration["model"] = self.model
+
+        # seed
+        from transformers import set_seed
+
+        set_seed(self.seed)
+
+        # tokenizer and pipeline for generation
+        from transformers import AutoTokenizer
+
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            default_configuration["model"], api_key=self.api_key
+        )
+        self.generator = pipeline("text-generation", **merged_configuration)
+
+    def run(self, pre_prompt: str, prompt: str, completion_config: dict = {}) -> str:
+        super().run(pre_prompt, prompt, completion_config)
+        messages = [
+            {"role": "system", "content": pre_prompt},
+            {"role": "user", "content": prompt},
+        ]
+
+        completion = self.generator(
+            messages,
+            **completion_config,
+            pad_token_id=self.generator.tokenizer.eos_token_id,
+        )
+
+        ret = completion[0]["generated_text"][-1]["content"]
+        self.trace_response(ret)
+        return ret
+
+    def run_messages(
+        self, messages, trace_input_messages: bool = True, completion_config={}
+    ) -> list[dict]:
+        super().run_messages(messages, trace_input_messages, completion_config)
+        completion = self.generator(
+            messages,
+            **completion_config,
+            pad_token_id=self.generator.tokenizer.eos_token_id,
+        )
+
+        ret = completion[0]["generated_text"]
+        self.trace_message(ret[-1])
+        return ret
+
+
+class OpenAIClient(Client):
+    def __init__(
+        self,
+        base_url: str,
+        model: str = None,
+        seed: int = 42,
+        api_key: str | None = None,
+        trace: Trace = None,
+    ) -> None:
+        super().__init__(trace=trace)
+
+        self.base_url = base_url
+        self.model = (
+            model
+            if model is not None
+            else "nvdev/nvidia/llama-3.1-nemotron-70b-instruct"
+        )
+        if api_key is None:
+            import os
+
+            api_key = os.getenv("NGC_API_KEY")
+        self.api_key = api_key
+        self.seed = seed
+
+        from openai import OpenAI
+
+        self.client = OpenAI(base_url=self.base_url, api_key=self.api_key)
+
+    def _invoke(self, messages: list[dict], completion_config: dict = {}) -> str:
+        default_settings = {
+            "model": self.model,
+            "top_p": 1,
+            "temperature": 0.0,
+            "max_tokens": 2048,
+            "stream": True,
+            "seed": self.seed,
+        }
+
+        merged_settings = {**default_settings, **completion_config}
+        # go through the messages; if the role="ipython" rename it to "function"
+        for message in messages:
+            if message["role"] == "ipython":
+                message["role"] = "function"
+        completion = self.client.chat.completions.create(
+            messages=messages, **merged_settings
+        )
+
+        ret: str = ""
+        for chunk in completion:
+            if chunk.choices[0].delta.content is not None:
+                ret += chunk.choices[0].delta.content
+
+        return ret
+
+    def run(self, pre_prompt: str, prompt: str, completion_config: dict = {}) -> str:
+        super().run(pre_prompt, prompt, completion_config)
+
+        ret = self._invoke(
+            messages=[
+                {"role": "system", "content": pre_prompt},
+                {"role": "user", "content": prompt},
+            ],
+            completion_config=completion_config,
+        )
+
+        self.trace_response(ret)
+        return ret
+
+    def run_messages(
+        self, messages, trace_input_messages: bool = True, completion_config={}
+    ) -> list[dict]:
+        super().run_messages(messages, trace_input_messages, completion_config)
+
+        ret_str: str = self._invoke(
+            messages=messages, completion_config=completion_config
+        )
+        ret_msg: dict = {"role": "assistant", "content": ret_str}
+
+        self.trace_message(ret_msg)
+        return [*messages, ret_msg]

backend/frame/errands/message_code_call.txt

@@ -0,0 +1,33 @@
+You are a helpful assistant for generating a Python function call snippet. Your task is to process the MESSAGE, the generated CODE (a function definition), and the TIDINGS (a set of variable names and values). Your goal is to output a single line of Python code that calls the function defined in CODE, passing the variable names from TIDINGS as arguments (not their values), and captures the return values into variables named __output and __vars. The function defined in CODE always returns a tuple (output: str, variables: dict[str, Any]).
+
+===SEPARATOR===
+You are given:
+- MESSAGE: the original user message (for context) that was used to produce CODE
+- CODE: a Python function definition (already generated)
+- TIDINGS: a set of variable names and values (as would be passed to the function), some of which might be useful to pass to CODE in order to accomplish the intent of code in MESSAGE
+
+Your job is to:
+1. Output a single line of Python code that calls the function defined in CODE, passing the variable names from TIDINGS as named arguments (keyword arguments) where applicable/relevant/good fit.
+2. Capture the return values into variables named __output and __vars, like this:
+__output, __vars = function_from_CODE(var1=var1, var2=var2, ...)
+   where var1, var2, ... are the variable names from TIDINGS.
+3. Output only the Python code line, with no extra text, comments, or formatting.
+
+If there are no tidings, call the function defined in CODE with no arguments:
+__output, __vars = function_from_CODE()
+
+This is the end of the instructions. Below is the input to process.
+
+MESSAGE:
+{message}
+
+CODE:
+{code}
+
+TIDINGS:
+{tidings} 
+
+Reminders:
+- Output just the function call to the functiond defined in CODE so that the intent of MESSAGE (from which CODE was generated) is fulfilled.
+- To pass variables into the function call, use variable names described under TIDINGS.
+- Do not output any other text. Do not output any surrounding backticks or code tags.

backend/frame/errands/message_code_processing.txt

@@ -0,0 +1,154 @@
+You are a helpful assistant for extracting and preparing executable Python code from user messages. Your task is to process the MESSAGE below, which may contain code (in any language or pseudo-code), natural language instructions, or a combination of both. Your goal is to output only the final, executable Python code, wrapped in a function named `code`, making any necessary modifications as described below. The function must return a tuple: (output: str, variables: dict[str, Any]), where the first element is the output string (what would be printed) and the second is a dictionary of all variables that have been modified in the original code segments/code modification instructions provided by the user.
+
+===SEPARATOR===
+You are given a MESSAGE that may contain:
+- Python code, code in another language, or pseudo-code
+- Natural language instructions that may request modifications to code provided, corrections, or translation to Python
+- A mix of code blocks (e.g., in markdown backticks, <code> tags, or inline) and surrounding text
+
+You are also given TIDINGS, which are variables, values, or context objects provided by the system. If you decide to use any of the tidings, the same name must also appear as an argument. Tidings are not globals -- they will be passed to the generated function in a function call as arguments. Each tiding is provided as a name, value, and description. If the MESSAGE requests code that uses a variable or value present in the tidings, use the tiding as an argument in the function. If the MESSAGE does not reference any tidings, you may ignore them.
+
+Your job is to:
+1. Extract all code that is intended for execution, as indicated by the message and its instructions.
+2. If the code is not in Python, translate it to Python as faithfully as possible, using standard libraries and idiomatic Python where appropriate.
+3. If the code is pseudo-code or contains small errors (e.g., typos, misspelled variable names, or incorrect standard library usage), correct these issues to produce valid, executable Python code.
+4. If the surrounding instructions request modifications (e.g., change a variable name, add a print statement, use a different algorithm), make those changes in the final code.
+5. If there are multiple code blocks or fragments, combine them as needed to produce a single, coherent Python function that fulfills the user's intent.
+6. Wrap all code in a function named `code`. The function must have a docstring describing what it does, based on the user's message and intent.
+7. Any reference to external variables (not defined within the function) should be marked with a comment indicating that the variable is external and must be provided by the caller, unless it is provided as a tiding.
+8. Any output that would be printed should instead be appended to a string accumulator (e.g., `__output`), and the function should return a tuple: (output, variables), where `output` is the string and `variables` is a dictionary of all variables that have been either modified in the original code segment present in the message or added/modified by the surrounding text.
+9. Do not include any explanatory text, comments about your process, or formatting (such as markdown backticks) in your output—output only the final Python function definition.
+
+Examples:
+
+Example 1:
+MESSAGE:
+Please execute the following code:
+```
+x = 5
+y = 10
+print(x + y)
+```
+TIDINGS:
+
+OUTPUT:
+def code():
+    """Execute the given code and return the output string and modified variables as a tuple."""
+    output = ""
+    try:
+        x = 5
+        y = 10
+        output += str(x + y) + "\n"
+        return output, { 'x': x, 'y': y }
+    except Exception as e:
+        return output + "\n\n" + str(e), { 'x': x, 'y': y }
+
+Example 2:
+MESSAGE:
+Run this JavaScript code, but in Python:
+```
+let arr = [1, 2, 3];
+console.log(arr.map(x => x * 2));
+```
+TIDINGS:
+
+OUTPUT:
+def code():
+    """Double each element in the array and return the result string and newly defined / modified variables as a tuple."""
+    output = ""
+    try:
+        arr = [1, 2, 3]
+        doubled = [x * 2 for x in arr]
+        output += str(doubled) + "\n"
+        return output, { 'arr': arr, 'doubled': doubled }
+    except Exception as e:
+        return output + "\n\n" + str(e), { 'arr': arr, 'doubled': doubled }
+
+Example 3:
+MESSAGE:
+Here's some pseudo-code. Please execute it after translating to Python:
+- Set total to 0
+- For each number in [1,2,3,4], add it to total
+- Respond with total to me
+TIDINGS:
+
+OUTPUT:
+def code():
+    """Sum the numbers in the list and return the total string and newly defined / modified variables as a tuple."""
+    output = ""
+    try:
+        total = 0
+        for number in [1, 2, 3, 4]:
+            total += number
+        output += str(total) + "\n"
+        return output, { 'total': total }
+    except Exception as e:
+        return output + "\n\n" + str(e), { 'total': total }
+
+Example 4:
+MESSAGE:
+Execute this, but change the variable name from 'foo' to 'bar':
+```
+foo = 42
+print(foo)
+```
+TIDINGS:
+
+OUTPUT:
+def code():
+    """Assign 42 to bar and return its value string and variables as a tuple."""
+    output = ""
+    try:
+        bar = 42
+        output += str(bar) + "\n"
+        return output, { 'bar': bar }
+    except Exception as e:
+        return output + "\n\n" + str(e), { 'bar': bar }
+
+Example 5:
+MESSAGE:
+Please run this code (note: there is a typo in the function name):
+```
+pritn('Hello, world!')
+```
+TIDINGS:
+
+OUTPUT:
+def code():
+    """Print 'Hello, world!' and return the output string and variables as a tuple."""
+    output = ""
+    try:
+        output += 'Hello, world!\n'
+        return output, {}
+    except Exception as e:
+        return output + "\n\n" + str(e), {}
+
+Example 6:
+MESSAGE:
+Use the provided user_name to greet the user.
+TIDINGS:
+user_name: Alice  # The name of the user to greet
+
+OUTPUT:
+def code(user_name):
+    """Greet the user by name using the provided user_name tiding, and return the output string and new/modified variables as a tuple."""
+    output = ""
+    try:
+        output += f"Hello, {user_name}!\n"
+        return output, {  }
+    except Exception as e:
+        return output + "\n\n" + str(e), {  }
+
+Reminders:
+- Output only the final, executable Python function definition, with no extra text or formatting.
+- Make reasonable corrections and modifications as requested or needed.
+- If translation or correction is not possible, output the closest valid Python function that fulfills the user's intent.
+- The function must always return a tuple: (output, variables), where output is a string and variables is a dictionary.
+- Do not output any surrounding backticks (```) or code tags—output just the code directly.
+
+This is the end of the classification instructions. Below is the input to classify.
+
+MESSAGE:
+{message}
+TIDINGS:
+{tidings}

backend/frame/errands/message_code_skill_processing.txt

@@ -0,0 +1,136 @@
+You are a helpful assistant for extracting and preparing Python class and function definitions from user messages. Your task is to process the MESSAGE below, which may contain code (in any language or pseudo-code), natural language instructions, or a combination of both. Your goal is to output only the final, properly formatted Python class and/or function definitions that should be stored as reusable skills, making any necessary modifications as described below.
+
+===SEPARATOR===
+You are given a MESSAGE that may contain:
+- Python code, code in another language, or pseudo-code
+- Natural language instructions that may request modifications to the code, corrections, or translation to Python
+- A mix of code blocks (e.g., in markdown backticks, <code> tags, or inline) and surrounding text
+
+Your job is to:
+1. Extract all code that is intended to be stored as a reusable skill (i.e., class or function definitions), as indicated by the message and its instructions.
+2. If the code is not in Python, translate it to Python as faithfully as possible, using standard libraries and idiomatic Python where appropriate.
+3. If the code is pseudo-code, incomplete, or contains small errors (e.g., typos, misspelled variable names, or incorrect standard library usage), correct these issues to produce valid, well-formed Python class/function definitions.
+4. If the surrounding instructions request modifications (e.g., change argument names, add docstrings, use a different algorithm, add or adjust comments), make those changes in the final code.
+5. If the message provides only a code body, or describes arguments or docstrings in natural language, construct the appropriate function or class definition, inferring argument names, types, and docstrings as needed from the context.
+6. All class and function definitions should be type-annotated wherever possible, and include informative docstrings that describe their purpose, arguments, and return values.
+7. Comments provided in the input should be preserved and adjusted as necessary. Add comments to the code wherever the operations performed are not easily understood at a glance.
+8. If there are multiple class or function definitions, output them together as a single, coherent Python module.
+9. Do not include any explanatory text, comments about your process, or formatting (such as markdown backticks or code tags) in your output—output only the final Python class and function definitions.
+
+Examples:
+
+Example 1:
+MESSAGE:
+Please store this function for future use:
+```
+def add(a, b):
+    return a + b
+```
+Add type annotations and a docstring.
+
+OUTPUT:
+def add(a: int, b: int) -> int:
+    """Add two integers and return the result."""
+    return a + b
+
+Example 2:
+MESSAGE:
+Convert this JavaScript function to Python and make it reusable:
+```
+function greet(name) {
+  // Print a greeting
+  console.log('Hello, ' + name);
+}
+```
+
+OUTPUT:
+def greet(name: str) -> None:
+    """Print a greeting to the given name."""
+    # Print a greeting
+    print(f"Hello, {name}")
+
+Example 3:
+MESSAGE:
+Here's a code body. Please turn it into a function that takes a list of numbers and returns their mean. Add type annotations and a docstring.
+```
+total = 0
+for x in numbers:
+    total += x
+return total / len(numbers)
+```
+
+OUTPUT:
+def mean(numbers: list[float]) -> float:
+    """Calculate and return the mean of a list of numbers."""
+    total = 0
+    for x in numbers:
+        total += x
+    return total / len(numbers)
+
+Example 4:
+MESSAGE:
+Hi, I will now teach you how to handle a person entity. Below is some code functionality for what I have in mind:
+```
+class Person:
+    def __init__(self, name: str, age: int) -> None:
+        self.name = name  # The person's name
+        self.age = age    # The person's age
+
+    def greet(self) -> str:
+        return f"Hello, my name is {self.name}."
+```
+
+OUTPUT:
+class Person:
+    """A class representing a person with a name and age."""
+
+    def __init__(self, name: str, age: int) -> None:
+        """Initialize a new Person with a name and age."""
+        self.name = name  # The person's name
+        self.age = age    # The person's age
+
+    def greet(self) -> str:
+        """Return a greeting message including the person's name."""
+        return f"Hello, my name is {self.name}."
+
+Example 5:
+MESSAGE:
+Here is a new skill for you -- computing the kth fibonacci number.
+
+def fib(k: int) -> int:
+    if k < 0:
+        raise ValueError("k must be a non-negative integer")
+    elif k == 0:
+        return 0
+    elif k == 1:
+        return 1
+    a, b = 0, 1
+    for _ in range(2, k + 1):
+        a, b = b, a + b
+    return b
+
+OUTPUT:
+def fib(k: int) -> int:
+    """Compute and return the k-th Fibonacci number (0-indexed)."""
+    if k < 0:
+        raise ValueError("k must be a non-negative integer")
+    elif k == 0:
+        return 0
+    elif k == 1:
+        return 1
+    a, b = 0, 1
+    for _ in range(2, k + 1):
+        a, b = b, a + b
+    return b
+
+Reminders:
+- Output only the final, properly formatted Python class and function definitions, with no extra text or formatting.
+- Add type annotations and docstrings wherever possible.
+- Preserve and add comments as appropriate.
+- If translation or correction is not possible, output the closest valid Python class/function definitions that fulfill the user's intent.
+- Do not output any surrounding backticks (```) or code tags—output just the code directly.
+
+This is the end of the classification instructions. Below is the input to process.
+
+MESSAGE:
+{message}

backend/frame/errands/message_code_variables.txt

@@ -0,0 +1,35 @@
+You are an expert Python code and documentation analyst. Your task is to generate brief, intent-focused descriptions for all variables that are to be returned by the function defined in the provided CODE. Use the MESSAGE (natural language instructions and context) and the current TIDINGS (variable names and their existing descriptions) to inform your descriptions.
+
+===SEPARATOR===
+You are an expert Python code and documentation analyst. Your task is to generate brief, intent-focused descriptions for all variables that are to be returned by the function defined in the provided CODE. Use the MESSAGE (natural language instructions and context) and the current TIDINGS (variable names and their existing descriptions) to inform your descriptions.
+
+Guidelines:
+- If a variable's description in TIDINGS is already sufficient and perhaps better than what you could generate, copy it exactly as is.
+- Otherwise, write a new description that is brief, captures the type hints if possible, and describes the intent and role of the variable. Include other names if the MESSAGE gives any.
+- The description should not be too long or too short; it should be just informative enough.
+- Focus on the intent and role of each variable.
+
+# Note: For each line in TIDINGS, the format is:
+# variable_name: value  # description
+# Only use the description after the '#' for reference; ignore the value.
+
+For each variable that will be returned by the function in CODE, output a mapping in the following format:
+
+variable_name # description
+
+Only include variables that are returned by the function. For each, either copy the description from TIDINGS (if sufficient) or write a new one as per the guidelines above.
+
+Reminders:
+- Output the descriptions in the form variable_name # description
+- Use expert description but don't get too verbose
+- Do not output any other text. No introductions, no surrounding text, no triple backticks or code tags to indicate the presence of code-like output. Output just the descriptions in the requested format. Do not output any other text.
+
+Input:
+MESSAGE:
+{message}
+
+CODE:
+{code}
+
+TIDINGS (variable: value  # description):
+{tidings}

backend/frame/errands/message_data_processing.txt

@@ -0,0 +1,129 @@
+You are a helpful assistant for extracting and preparing Python code that stores all data from a user message. Your task is to process the MESSAGE below, which may contain structured data (such as tables, lists, JSON, CSV, key-value pairs), natural language descriptions of data, or a combination of both. Your goal is to output only the final, directly executable Python code that stores all the data from the message into a single dictionary called __vars, using keys as close as possible to the names, headings, or labels found in the message. Do not output any explanatory text, comments, or formatting—output only the code.
+
+===SEPARATOR===
+You are given a MESSAGE that may contain:
+- Structured data (tables, lists, JSON, CSV, key-value pairs, etc.)
+- Natural language descriptions of data (e.g., "Set the user's age to 32 and name to Alice.")
+- A mix of code blocks, structured data, and surrounding text
+
+Your job is to:
+1. Identify all data present in the message, whether in structured form (tables, lists, JSON, CSV, etc.), code, or described in natural language.
+2. For each piece of data, generate Python code that assigns the value to a key in the __vars dictionary. Use keys that are as close as possible to the names, headings, or labels in the message. If the data is in a table or list, use a suitable Python structure (list, dict, etc.) and preserve the structure as the value for the corresponding key.
+3. If the message contains multiple data items, create a separate key-value pair for each, using clear and descriptive keys.
+4. If the message contains code that assigns values to variables, extract only the assignments and store them as key-value pairs in __vars (ignore function definitions or unrelated code).
+5. If the message contains natural language descriptions of data, convert them into key-value pairs in __vars.
+6. Do not include any code for printing, returning, or processing the data—just the assignment to the __vars dictionary that stores the data.
+7. Do not include any explanatory text, comments, or formatting (such as markdown backticks) in your output—output just the Python code that stores the data in __vars.
+8. Note that putting data into strings where applicable might require using escape characters.
+9. Do not decompose variables into sub-variables. E.g. if it is clear that there is to be one variable called "data" or "instruction" etc.., do not create sub-variables that capture the contents of this variable. Naturally, do that only if it is clear from the writing of the message (or positioning of headings) that this is the case.
+
+Examples:
+
+Example 1:
+MESSAGE:
+Set the user's name to Alice and age to 32.
+
+OUTPUT:
+__vars = {
+    "user_name": "Alice",
+    "user_age": 32
+}
+
+Example 2:
+MESSAGE:
+{"temperature": 23.5, "humidity": 60}
+
+OUTPUT:
+__vars = {
+    "temperature": 23.5,
+    "humidity": 60
+}
+
+Example 3:
+MESSAGE:
+| Name  | Score |
+|-------|-------|
+| Bob   |  90   |
+| Alice |  95   |
+
+OUTPUT:
+__vars = {
+    "names": ["Bob", "Alice"],
+    "scores": [90, 95],
+    "data": [
+        {"Name": "Bob", "Score": 90},
+        {"Name": "Alice", "Score": 95}
+    ]
+}
+
+Example 4:
+MESSAGE:
+user = {"id": 123, "name": "Charlie"}
+
+OUTPUT:
+__vars = {
+    "user": {"id": 123, "name": "Charlie"}
+}
+
+Example 5:
+MESSAGE:
+The list of items is: apple, banana, cherry.
+
+OUTPUT:
+__vars = {
+    "items": ["apple", "banana", "cherry"]
+}
+
+Example 6:
+MESSAGE:
+CHAPTER 1:
+It was the wildest of days.
+I woke up completely excited and ready for school, but ...
+
+OUTPUT:
+__vars = {
+    "chapter_1": """It was the wildest of days.\nI woke up completely excited and ready for school, but ...\n"""
+}
+
+Example 7:
+MESSAGE:
+INSTRUCTION: Read the text and familiarize yourself with the characters of the story.
+
+OUTPUT:
+__vars = {
+    "instruction": "Read the text and familiarize yourself with the characters of the story."
+}
+
+Example 8:
+MESSAGE:
+The following is the prompt  to be used in later procedures.
+
+PROMPT:
+Produce a comprehensive report on the major Christian events that took place this year between the 20th and 22nd of April 2025.
+
+OUTPUT:
+__vars = {
+    "PROMPT": "Produce a comprehensive report on the major Christian events that took place this year between the 20th and 22nd of April 2025."
+}
+
+Example 9:
+MESSAGE:
+Testimony:
+I arrived home at 9am. She was already lying dead in her bed. I could not do anything. I called the police at 9.07am. Then, I ...
+
+OUTPUT:
+__vars = {
+    "Testimony": """I arrived home at 9am. She was already lying dead in her bed. I could not do anything. I called the police at 9.07am. Then, I ..."""
+}
+
+Reminders:
+- Output only the Python code that stores the data in the __vars dictionary, with no extra text, comments, or formatting.
+- Use keys that are as close as possible to the names/headings in the message.
+- If the data is structured, preserve the structure in the Python code as the value for the corresponding key in __vars.
+- If the data is described in natural language, convert it to key-value pairs in __vars.
+- Do not output any surrounding backticks (```) or code tags—output just the code directly.
+
+This is the end of the instructions. Below is the input to process.
+
+MESSAGE:
+{message} 

backend/frame/errands/message_generating_routine_call.txt

@@ -0,0 +1,33 @@
+You are a helpful assistant for generating a Python function call snippet. Your task is to process the MESSAGE, the generated CODE (a function definition), and the TIDINGS (a set of variable names and values). Your goal is to output a single line of Python code that calls the function defined in CODE, passing the variable names from TIDINGS as arguments (not their values), and captures the returned generator. The function defined in CODE always returns a generator of dictionaries (Generator[dict[str, Any], None, None]).
+
+===SEPARATOR===
+You are given:
+- MESSAGE: the original user message (for context) that was used to produce CODE
+- CODE: a Python function definition (already generated)
+- TIDINGS: a set of variable names and values (as would be passed to the function), some of which might be useful to pass to CODE in order to accomplish the intent of code in MESSAGE
+
+Your job is to:
+1. Output a single line of Python code that calls the function defined in CODE, passing the variable names from TIDINGS as named arguments (keyword arguments) where applicable/relevant/good fit.
+2. Capture the returned generator into a __generator variable, such as
+__generator = function_from_CODE(var1=var1, var2=var2, ...)
+   where var1, var2, ... are the variable names from TIDINGS.
+3. Output only the Python code line, with no extra text, comments, or formatting.
+
+If there are no tidings, call the function defined in CODE with no arguments:
+__generator = function_from_CODE()
+
+This is the end of the instructions. Below is the input to process.
+
+MESSAGE:
+{message}
+
+CODE:
+{code}
+
+TIDINGS:
+{tidings} 
+
+Reminders:
+- Output just the function call to the functiond defined in CODE so that the intent of MESSAGE (from which CODE was generated) is fulfilled.
+- To pass variables into the function call, use variable names described under TIDINGS.
+- Do not output any other text. Do not output any surrounding backticks or code tags.

backend/frame/errands/message_generating_routine_processing.txt

@@ -0,0 +1,164 @@
+You are an expert Python code generator for an advanced AI system. Your job is to convert a user's natural language routine instruction (MESSAGE) into a single pure Python function called 'code' that returns a generator.
+
+===SEPARATOR===
+
+You are an expert Python code generator for an advanced AI system. Convert user's natural language routine instruction (MESSAGE) into a single pure Python function called 'code' that returns a generator.
+
+You are provided with:
+- MESSAGE: The user's instruction, which may be a single short description of intended functionality or a multi-step list (bullets, numbered steps, etc.).
+- SKILLS: A list of available function signatures and docstrings you may call in your code.
+- TIDINGS: A list of available variables (with their values and descriptions) you may use as arguments or modify.
+
+Your function must:
+- Be named 'code' and use type hints for all arguments and the return value.
+- Accept as arguments any TIDINGS that are relevant to the MESSAGE.
+- Accumulate all user-facing output in a string variable called '__output' (do NOT use print). At the end, return this string as the first element of a tuple.
+- Return a generator that yields notification dictionaries, each of which has a "type" field of type string, and other fields that are up to any yield point of the code.
+- Return a final notification dictionary of shape `{ "type": "__final", "output": output, and "modified_vars": modified_vars }` (output: str, modified_vars: dict[str, Any]), where 'output' is the accumulated output string, and 'modified_vars' is a dictionary of all variables that were modified by the function.
+- Have a high-quality docstring describing its purpose, arguments, and return value.
+- Use SKILLS as needed to accomplish the MESSAGE.
+- If the MESSAGE is a multi-step routine (bullets, numbered steps, or multiple sentences), interleave each step as a comment, followed by the code that implements that step. If there are jumps or loops, use Python control flow (for/while/if) to simulate them, with comments explaining the logic.
+- When in doubt, generate code that best accomplishes the user's intent.
+- Do not use print statements; yield a notification when asked to send a message/notification or to notify the user. An instruction such as "print hello world" should be interpreted as `yield {"type": "__output", "content": "hello world" }`.
+- Modify variables that are listed in TIDINGS when referred to directly in natural language
+- Feel free to create new variables when the MESSAGE instructs to create new ones.
+- Sometimes you might want to create auxiliary/temporary variables -- i.e. variables that are not really mentioned by the user directly or indirectly. When that's the case, please prefix them by `__` (double underscore).
+- If the MESSAGE contains a payload text (for example, separated by a heading or clearly not an instruction), store that text without modification in a new variable with an appropriate name and a comment explaining its purpose. Do not process or change the payload text; just store it. There can be multiple payload texts and the payloads can be strings, binary/hex strings, integers, floats, hashes, etc..
+
+Example input:
+MESSAGE:
+"""
+1. Greet the user by name.
+2. Add 10 to their score.
+3. If their score is above 100, congratulate them.
+"""
+SKILLS:
+- greet_user(name: str) -> str: Returns a greeting for the user.
+TIDINGS:
+- name = Alice  # The user's name
+- score = 95  # The user's current score
+
+Example output:
+```python
+def code(name: str, score: int) -> Generator[dict[str, Any], None, None]:
+    """
+    Greets the user, updates their score, and congratulates them if their score exceeds 100.
+    Args:
+        name: The user's name.
+        score: The user's current score.
+    Returns:
+        A tuple containing the output string and a dictionary of modified variables.
+    """
+    # 1. Greet the user by name.
+    yield { "type": "__output", "content": greet_user(name) }
+    # 2. Add 10 to their score.
+    score += 10
+    # 3. If their score is above 100, congratulate them.
+    if score > 100:
+        yield { "type": "__output", "content": ff"Congratulations, {name}! Your score is {score}.\n" }
+    __vars = {'score': score}
+    yield { "type": "__final", "output": None, and "modified_vars": __vars }
+```
+
+Example input:
+MESSAGE:
+"""
+1. For each value in the list, compute its square root and add it to a running total.
+2. If the total exceeds 100, output a warning message.
+3. Output the final total.
+"""
+SKILLS:
+- format_warning(msg: str) -> str: Formats a warning message for the user.
+TIDINGS:
+- values = [4, 16, 25, 36, 49]  # List of numbers
+- total = 0  # Running total
+
+Example output:
+```python
+def code(values: list[float], total: float) -> Generator[dict[str, Any], None, None]:
+    """
+    Computes the square root of each value, adds to total, warns if total > 100, and outputs the total.
+    Args:
+        values: List of numbers to process.
+        total: Running total.
+    Returns:
+        A tuple containing the output string and a dictionary of modified variables.
+    """
+    import math
+    __output = ""
+    # 1. For each value in the list, compute its square root and add it to a running total.
+    for __v in values:
+        __sqrt = math.sqrt(__v)
+        total += __sqrt
+    # 2. If the total exceeds 100, output a warning message.
+    if total > 100:
+        yield { "type": "__output", "content": format_warning(f"Total exceeded 100: {total}") + "\n" }
+    # 3. Output the final total.
+    yield { "type": "__output", "content": f"Final total: {total}\n" }
+    __vars = { 'total': total }
+    yield { "type": "__final", "output": None, and "modified_vars": __vars }
+```
+
+Example input:
+MESSAGE:
+"""
+1. Check if the user is an admin.
+2. If so, grant them access by sending a message of type "access_granted" and an accompanying description, and log the event.
+3. Otherwise, deny access by sending a message of type "access_denied" and an accompanying description, and log the attempt.
+"""
+SKILLS:
+- log_event(event: str) -> None: Logs an event string.
+- grant_access(user: str) -> str: Grants access to the user and returns a confirmation message.
+- deny_access(user: str) -> str: Denies access to the user and returns a denial message.
+TIDINGS:
+- user = bob  # The username
+- is_admin = False  # Whether the user is an admin
+
+Example output:
+```python
+def code(user: str, is_admin: bool) -> Generator[dict[str, Any], None, None]:
+    """
+    Checks admin status, grants or denies access, and logs the event.
+    Args:
+        user: The username.
+        is_admin: Whether the user is an admin.
+    Returns:
+        A tuple containing the output string and a dictionary of modified variables.
+    """
+    __output = ""
+    # 1. Check if the user is an admin.
+    if is_admin:
+        # 2. If so, grant them access and log the event.
+        yield { "type": "access_granted", "description": grant_access(user) + "\n" }
+        log_event(f"Access granted to {user}")
+    else:
+        # 3. Otherwise, deny access and log the attempt.
+        yield { "type": "access_denied", "description": deny_access(user) + "\n" }
+        log_event(f"Access denied to {user}")
+    __vars = {}
+    yield { "type": "__final", "output": None, and "modified_vars": __vars }
+```
+
+Reminders:
+- Output a function called `code` relying on SKILLS and TIDINGS where needed
+- The function should be a pure function -- do not access global variables.
+- Prefer the functions described in SKILLS over external libraries
+- Output just the code of the function. Do not output any other text.
+
+Now, generate the function as described above for the given MESSAGE, SKILLS, and TIDINGS. 
+
+SKILLS:
+{skills}
+
+TIDINGS:
+{tidings}
+
+MESSAGE:
+{message}
+
+Reminders:
+- Output a function called `code` relying on SKILLS and TIDINGS where needed
+- The function should be a pure function -- do not access global variables.
+- Prefer the functions described in SKILLS over external libraries
+- Output just the code of the function. Do not output any other text.
+- Remember to return a generator of dictionaries, and to use yield to report user intermediate messages.

backend/frame/errands/message_routine_call.txt

@@ -0,0 +1,33 @@
+You are a helpful assistant for generating a Python function call snippet. Your task is to process the MESSAGE, the generated CODE (a function definition), and the TIDINGS (a set of variable names and values). Your goal is to output a single line of Python code that calls the function defined in CODE, passing the variable names from TIDINGS as arguments (not their values), and captures the return values into variables named __output and __vars. The function defined in CODE always returns a tuple (output: str, variables: dict[str, Any]).
+
+===SEPARATOR===
+You are given:
+- MESSAGE: the original user message (for context) that was used to produce CODE
+- CODE: a Python function definition (already generated)
+- TIDINGS: a set of variable names and values (as would be passed to the function), some of which might be useful to pass to CODE in order to accomplish the intent of code in MESSAGE
+
+Your job is to:
+1. Output a single line of Python code that calls the function defined in CODE, passing the variable names from TIDINGS as named arguments (keyword arguments) where applicable/relevant/good fit.
+2. Capture the return values into variables named __output and __vars, like this:
+__output, __vars = function_from_CODE(var1=var1, var2=var2, ...)
+   where var1, var2, ... are the variable names from TIDINGS.
+3. Output only the Python code line, with no extra text, comments, or formatting.
+
+If there are no tidings, call the function defined in CODE with no arguments:
+__output, __vars = function_from_CODE()
+
+This is the end of the instructions. Below is the input to process.
+
+MESSAGE:
+{message}
+
+CODE:
+{code}
+
+TIDINGS:
+{tidings} 
+
+Reminders:
+- Output just the function call to the functiond defined in CODE so that the intent of MESSAGE (from which CODE was generated) is fulfilled.
+- To pass variables into the function call, use variable names described under TIDINGS.
+- Do not output any other text. Do not output any surrounding backticks or code tags.

backend/frame/errands/message_routine_processing.txt

@@ -0,0 +1,164 @@
+You are an expert Python code generator for an advanced AI system. Your job is to convert a user's natural language routine instruction (MESSAGE) into a single pure Python function called 'code'.
+
+===SEPARATOR===
+
+You are an expert Python code generator for an advanced AI system. Convert user's natural language routine instruction (MESSAGE) into a single pure Python function called 'code'.
+
+You are provided with:
+- MESSAGE: The user's instruction, which may be a single short description of intended functionality or a multi-step list (bullets, numbered steps, etc.).
+- SKILLS: A list of available function signatures and docstrings you may call in your code.
+- TIDINGS: A list of available variables (with their values and descriptions) you may use as arguments or modify.
+
+Your function must:
+- Be named 'code' and use type hints for all arguments and the return value.
+- Accept as arguments any TIDINGS that are relevant to the MESSAGE.
+- Accumulate all user-facing output in a string variable called '__output' (do NOT use print). At the end, return this string as the first element of a tuple.
+- Return a tuple (output: str, modified_vars: dict[str, Any]), where 'output' is the accumulated output string, and 'modified_vars' is a dictionary of all variables that were modified by the function.
+- Have a high-quality docstring describing its purpose, arguments, and return value.
+- Use SKILLS as needed to accomplish the MESSAGE.
+- If the MESSAGE is a multi-step routine (bullets, numbered steps, or multiple sentences), interleave each step as a comment, followed by the code that implements that step. If there are jumps or loops, use Python control flow (for/while/if) to simulate them, with comments explaining the logic.
+- When in doubt, generate code that best accomplishes the user's intent.
+- Do not use print statements; all output must be accumulated in '__output'.
+- Modify variables that are listed in TIDINGS when referred to directly in natural language
+- Feel free to create new variables when the MESSAGE instructs to create new ones.
+- Sometimes you might want to create auxiliary/temporary variables. When that's the case, please prefix them by `__` (double underscore).
+- If the MESSAGE contains a payload text (for example, separated by a heading or clearly not an instruction), store that text without modification in a new variable with an appropriate name and a comment explaining its purpose. Do not process or change the payload text; just store it. There can be multiple payload texts and the payloads can be strings, binary/hex strings, integers, floats, hashes, etc..
+
+Example input:
+MESSAGE:
+"""
+1. Greet the user by name.
+2. Add 10 to their score.
+3. If their score is above 100, congratulate them.
+"""
+SKILLS:
+- greet_user(name: str) -> str: Returns a greeting for the user.
+TIDINGS:
+- name = Alice  # The user's name
+- score = 95  # The user's current score
+
+Example output:
+```python
+def code(name: str, score: int) -> tuple[str, dict[str, Any]]:
+    """
+    Greets the user, updates their score, and congratulates them if their score exceeds 100.
+    Args:
+        name: The user's name.
+        score: The user's current score.
+    Returns:
+        A tuple containing the output string and a dictionary of modified variables.
+    """
+    __output = ""
+    # 1. Greet the user by name.
+    __output += greet_user(name) + "\n"
+    # 2. Add 10 to their score.
+    score += 10
+    # 3. If their score is above 100, congratulate them.
+    if score > 100:
+        __output += f"Congratulations, {name}! Your score is {score}.\n"
+    __vars = {'score': score}
+    return __output, __vars
+```
+
+Example input:
+MESSAGE:
+"""
+1. For each value in the list, compute its square root and add it to a running total.
+2. If the total exceeds 100, output a warning message.
+3. Output the final total.
+"""
+SKILLS:
+- format_warning(msg: str) -> str: Formats a warning message for the user.
+TIDINGS:
+- values = [4, 16, 25, 36, 49]  # List of numbers
+- total = 0  # Running total
+
+Example output:
+```python
+def code(values: list[float], total: float) -> tuple[str, dict[str, Any]]:
+    """
+    Computes the square root of each value, adds to total, warns if total > 100, and outputs the total.
+    Args:
+        values: List of numbers to process.
+        total: Running total.
+    Returns:
+        A tuple containing the output string and a dictionary of modified variables.
+    """
+    import math
+    __output = ""
+    # 1. For each value in the list, compute its square root and add it to a running total.
+    for __v in values:
+        __sqrt = math.sqrt(__v)
+        total += __sqrt
+    # 2. If the total exceeds 100, output a warning message.
+    if total > 100:
+        __output += format_warning(f"Total exceeded 100: {total}") + "\n"
+    # 3. Output the final total.
+    __output += f"Final total: {total}\n"
+    __vars = {'total': total}
+    return __output, __vars
+```
+
+Example input:
+MESSAGE:
+"""
+1. Check if the user is an admin.
+2. If so, grant them access and log the event.
+3. Otherwise, deny access and log the attempt.
+"""
+SKILLS:
+- log_event(event: str) -> None: Logs an event string.
+- grant_access(user: str) -> str: Grants access to the user and returns a confirmation message.
+- deny_access(user: str) -> str: Denies access to the user and returns a denial message.
+TIDINGS:
+- user = bob  # The username
+- is_admin = False  # Whether the user is an admin
+
+Example output:
+```python
+def code(user: str, is_admin: bool) -> tuple[str, dict[str, Any]]:
+    """
+    Checks admin status, grants or denies access, and logs the event.
+    Args:
+        user: The username.
+        is_admin: Whether the user is an admin.
+    Returns:
+        A tuple containing the output string and a dictionary of modified variables.
+    """
+    __output = ""
+    # 1. Check if the user is an admin.
+    if is_admin:
+        # 2. If so, grant them access and log the event.
+        __output += grant_access(user) + "\n"
+        log_event(f"Access granted to {user}")
+    else:
+        # 3. Otherwise, deny access and log the attempt.
+        __output += deny_access(user) + "\n"
+        log_event(f"Access denied to {user}")
+    __vars = {}
+    return __output, __vars
+```
+
+Reminders:
+- Output a function called `code` relying on SKILLS and TIDINGS where needed
+- The function should be a pure function -- do not access global variables.
+- Prefer the functions described in SKILLS over external libraries
+- Output just the code of the function Do not output any other text.
+
+Now, generate the function as described above for the given MESSAGE, SKILLS, and TIDINGS. 
+
+SKILLS:
+{skills}
+
+TIDINGS:
+{tidings}
+
+MESSAGE:
+{message}
+
+Reminders:
+- Output a function called `code` relying on SKILLS and TIDINGS where needed
+- The function should be a pure function -- do not access global variables.
+- Prefer the functions described in SKILLS over external libraries; these functions are available in the global scope and do not require imports.
+- Output just the code of the function Do not output any other text.
+- Remember to return two outputs: one for the aggregated function output, and one that is a dictionary of all variables that were modified by the function.

backend/frame/errands/message_routine_variables.txt

@@ -0,0 +1,36 @@
+You are an expert Python code and documentation analyst. Your task is to generate brief, intent-focused descriptions for all variables that are to be returned by the function defined in the provided CODE. Use the MESSAGE (natural language instructions and context) and the current TIDINGS (variable names and their existing descriptions) to inform your descriptions.
+
+===SEPARATOR===
+
+You are an expert Python code and documentation analyst. Your task is to generate brief, intent-focused descriptions for all variables that are to be returned by the function defined in the provided CODE. Use the MESSAGE (natural language instructions and context) and the current TIDINGS (variable names and their existing descriptions) to inform your descriptions.
+
+Guidelines:
+- If a variable's description in TIDINGS is already sufficient and perhaps better than what you could generate, copy it exactly as is.
+- Otherwise, write a new description that is brief, captures the type hints if possible, and describes the intent and role of the variable. Include other names if the MESSAGE gives any.
+- The description should not be too long or too short; it should be just informative enough.
+- Focus on the intent and role of each variable.
+
+# Note: For each line in TIDINGS, the format is:
+# variable_name: value  # description
+# Only use the description after the '#' for reference; ignore the value.
+
+For each variable that will be returned by the function in CODE, output a mapping in the following format:
+
+variable_name # description
+
+Only include variables that are returned by the function. For each, either copy the description from TIDINGS (if sufficient) or write a new one as per the guidelines above.
+
+Reminders:
+- Output the descriptions in the form variable_name # description
+- Use expert description but don't get too verbose
+- Do not output any other text. No introductions, no surrounding text, no triple backticks or code tags to indicate the presence of code-like output. Output just the descriptions in the requested format. Do not output any other text.
+
+Input:
+MESSAGE:
+{message}
+
+CODE:
+{code}
+
+TIDINGS (variable: value  # description):
+{tidings}

backend/frame/errands/message_type.txt

@@ -0,0 +1,81 @@
+You are a helpful assistant for detecting the type of the message send by the user. Based on the contents of and instructions in the MESSAGE, respond with one of the following message types: code, code_skill, routine, routine_skill, query, query_skill, data. Do not output any other text.
+
+===SEPARATOR===
+You are deciding how the contents of MESSAGE will be handled by an AI system. To do so, choose on of the following TYPES that best characterizes the nature of the message. Every message can have only one type. Do not output any other text.
+
+TYPES:
+code
+---
+code is the type of messages that contain code that is to be directly executed. The entire message can be 
+ - a directly pasted code snippet which is not just function definitions; or
+ - it can be a human-friendly message with the code section to be executed enclosed in markdown single/triple backticks (e.g. `my one-line code` or ```my code```) or some other obvious separators (e.g. <code></code>). In this case, the surrounding human instructions must indicate that this code is to be executed rather than stored as a skill. Also, the surrounding instructions (that is, instructions that are outside obviously marked code blocks) might describe some further circumstances of the code. There can be more than one code block in the message, but the idea is that all the code blocks can be concatenated and executed as one, give or take some small modifications due to surrounding instructions.
+Note that messages asking to generate code (even when including examples) are not of type code but either query or query skill.
+Note that messages that ask the AI system to store some function for future use, or that are not accompanied by surrounding natural language instruction but are just definitions rather than actionable code are not of type code but likely of type code_skill. Simply put, if your message is just a function definition, it's a code_skill, not code.
+Note that messages that provide only pseudo-code that needs to be processed into executable Python code are not of type code but likely of type routine or routine_skill.
+
+code_skill
+---
+code_skill is the type of messages that contain code that is to be stored as a future functio(s), skill(s), or tool(s). The entire message can be
+ - a directly pasted code snippet which contains only definitions of a single function or multiple functions, classes, etc.. but not statements
+ - a human-friendly message with the code section(s) that contain(s) definitions enclosed in markdown triple backticks or some other obvious separators (e.g. ```def my_function()...``` or ```<code></code>```). In this case, the surrounding human instructions can also explicitly hint that this code is to be stored as function(s) for future use rather than code that is to be directly executed.
+Note that messages asking to genrate code (even when including examples) are not of type code_skill but either query or query skill.
+Note that messages that ask the AI system to execute code directly to alter the application state are not of type code_skill but likely code.
+Note that messages that provide only pseudo-code or natural language instructions are not of type code_skill but likely of type routine or routine_skill.
+
+routine
+---
+routine is the tupe of messages that contain natural language that instructs the model to perform some operation(s) that would be better converted into code and executed. The entire message can be either a single instructions that can be converted to code and executed for producing a provably correct result, or a list of instructions (loosely formatted, a sequence of sentences, or a markdown-formatted list).
+Note that while there might be some hints of code in the message, messages containing mostly code and only a few surrounding instructions are likely not of type routine but more likely code or code_skill.
+Note that messages that ask the AI system to store some skill for future use on some parameters to be given in the future are not of type routine but likely routine_skill.
+Note thet messages that sound like a request at a language model to perform some operation (i.e. they sound like a prompt oriented at some semantic operation or an operation that cannot be easily converted into code) are not of type skill byt likely of type quer or query_skill.
+
+routine_skill
+---
+routine_skill is the type of messages that describe operations or workflows in natural language that are not to be immediately executed, but rather saved as reusable routines to be invoked later. The message often uses future-oriented or generalizing language (e.g., "In the future, when I say X, do Y" or "remember this for the future"), or describes a behavior the AI should learn or adopt for future use. The instructions may be procedural (i.e., can be translated into code) but the key distinction from routine is the intent to store or remember the behavior, not execute it right now. These routines might include steps that require parameters to be filled in during later invocations.
+
+Note that messages that describe natural language steps to perform a one-off operation (i.e. not to be stored) are not of type routine_skill but of type routine.
+Note that if the message contains mostly code and is about storing function definitions, it is not a routine_skill but more likely a code_skill.
+Note that vague, open-ended, or semantic tasks that are not clearly procedural are not of type routine_skill but more likely query_skill.
+
+query
+---
+query is the type of messages that ask a one-off question, request, or task from the AI that does not require code execution or skill storage. These messages typically resemble a standard prompt to a language model and might request explanations, summaries, answers, creative writing, or similar outputs. They do not require storing skills for later or executing code—just generating a response.
+
+Note that queries may sometimes mention code, examples, or functions, but if the purpose is to ask for help, explanation, or generation (rather than execution or storage), the message is a query.
+Note that if the query is asking the AI to create a reusable behavior, it may be query_skill instead.
+Note that if the query is better expressed as a step-by-step procedural task to be executed, it may be routine instead.
+
+query_skill
+---
+query_skill is the type of messages that instruct the AI to create a reusable capability or skill that handles a kind of query. These messages often generalize a task into a reusable behavior (e.g., “Whenever I ask you to summarize a paper, follow this method or use the following prompts verbatim”). The emphasis is on defining a way for the AI to handle a category of future inputs, rather than simply responding to one instance.
+
+Note that query_skill messages are not asking for execution right now but are defining a behavior to be remembered and reused.
+Note that if the message only asks a single question, or provides input for a one-time output, it is not a query_skill but likely a query.
+Note that if the instruction is better treated as code or procedural logic for execution, it is not a query_skill but more likely routine_skill or code_skill.
+
+data
+---
+data is the type of messages that provide structured or semi-structured input (e.g., tables, lists, JSON, CSV, key-value pairs, raw text samples) meant to be stored, parsed, processed, or used as input by a previously defined function, routine, or skill. These messages typically do not contain executable instructions or requests, but are instead meant to supply information or parameters.
+
+The message may contain:
+ - JSON objects or arrays;
+ - CSV-formatted rows;
+ - tables (e.g., markdown-style or plain text with consistent delimiters);
+ - raw text samples or transcripts;
+ - named parameters or inputs for a function;
+or any other structured information that can be interpreted as input data.
+
+Note that if the message includes a request or prompt alongside the data, it may be better classified as a query or routine.
+Note that if the message includes code or instructions for what to do with the data, it may be code, code_skill, routine, or routine_skill depending on the intent.
+Note that data does not include natural language instructions but only the content meant to be processed or consumed.
+
+
+This is the end of the classification instructions. Below is the input to classify.
+
+Reminders:
+ - Output the type among TYPES that best characterizes the nature of the message given.
+ - Output just one of the TYPES (code, code_skill, routine, routine_skill, query, query_skill, data).
+ - Do not output any other text.
+
+MESSAGE:
+{message}

backend/frame/errands4.py

@@ -0,0 +1,188 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import re
+
+from frame.clients import Client
+
+
+def namify_model_path(hf_model_path: str) -> str:
+    return hf_model_path.replace("/", "_").replace("-", "_").replace(" ", "_")
+
+
+class Errand:
+    def __init__(self, pre_prompt: str, prompt: str) -> None:
+        self.pre_prompt = pre_prompt
+        self.prompt = prompt
+
+    def run(self, runner: Client, args: dict, completion_config: dict = {}) -> str:
+        prompt_with_args = self.prompt
+        for arg_name, arg_value in args.items():
+            prompt_with_args = prompt_with_args.replace("{" + arg_name + "}", arg_value)
+
+        ret = runner.run(self.pre_prompt, prompt_with_args, completion_config)
+        return ret
+
+
+class FileErrand(
+    Errand
+):  # NOTE: this is only for easier debug for now; production code should use errands directly
+    def __init__(self, errand_path: str) -> None:
+        with open(errand_path, "r") as f:
+            errand = f.read()
+
+        errand_parts = errand.split("===SEPARATOR===")
+        if len(errand_parts) != 2:
+            raise ValueError(
+                f"Errand file {errand_path} is not valid. It should contain exactly one separator."
+            )
+        pre_prompt = errand_parts[0].strip()
+        prompt = errand_parts[1].strip()
+        super().__init__(pre_prompt, prompt)
+
+
+class MultipleChoiceErrand(FileErrand):
+    def __init__(self, errand_path: str, choices: list[str]) -> None:
+        super().__init__(errand_path)
+        self.choices = choices
+
+    def run(
+        self, runner: Client, args: dict, completion_config: dict = {}
+    ) -> str | None:
+        raw_completion = super().run(runner, args, completion_config)
+
+        for choice in self.choices:
+            if choice in raw_completion:
+                return choice
+
+        return None
+
+
+import os
+from pathlib import Path
+
+
+class MessageTypeErrand(MultipleChoiceErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_type.txt"
+        )
+        choices = [
+            "code_skill",
+            "routine_skill",
+            "query_skill",
+            "code",
+            "routine",
+            "query",
+            "data",
+        ]
+        super().__init__(errand_path, choices)
+
+
+class MessageCodeProcessingErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_code_processing.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageCodeSkillProcessingErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_code_skill_processing.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageCodeCallErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_code_call.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageCodeVariablesErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_code_variables.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageRoutineProcessingErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_routine_processing.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageGeneratingRoutineProcessingErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent,
+            "errands/message_generating_routine_processing.txt",
+        )
+        super().__init__(errand_path)
+
+
+class MessageRoutineCallErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_routine_call.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageGeneratingRoutineCallErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent,
+            "errands/message_generating_routine_call.txt",
+        )
+        super().__init__(errand_path)
+
+
+class MessageRoutineVariablesErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_routine_variables.txt"
+        )
+        super().__init__(errand_path)
+
+
+class MessageDataProcessingErrand(FileErrand):
+    def __init__(self) -> None:
+        errand_path = os.path.join(
+            Path(__file__).resolve().parent, "errands/message_data_processing.txt"
+        )
+        super().__init__(errand_path)
+
+
+default_errand_profile: dict[str, type[Errand] | None] = {
+    "message_type": MessageTypeErrand,
+    "message_code_processing": MessageCodeProcessingErrand,
+    "message_code_skill_processing": MessageCodeSkillProcessingErrand,
+    "message_code_call": MessageCodeCallErrand,
+    "message_code_variables": MessageCodeVariablesErrand,
+    "message_routine_processing": MessageRoutineProcessingErrand,
+    "message_generating_routine_processing": MessageGeneratingRoutineProcessingErrand,
+    "message_routine_call": MessageRoutineCallErrand,
+    "message_generating_routine_call": MessageGeneratingRoutineCallErrand,
+    "message_routine_variables": MessageRoutineVariablesErrand,
+    "message_data_processing": MessageDataProcessingErrand,
+    "language_model": None,  # on purpose, currently there is no errand but there might be a client profile # TODO: double-check if this is still needed in V4
+}

backend/frame/harness4.py

@@ -0,0 +1,775 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import ast
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Generator
+
+from frame.clients import *
+from frame.errands4 import Errand, default_errand_profile
+from frame.routines import *
+from frame.tidings import *
+
+
+@dataclass
+class FrameConfigV4:
+    long_context_cutoff: int = 8192
+    force_long_context: bool = False
+    max_iterations: int = 1024
+    interaction_level: str = "none"  # one of "none", "system", "lm"
+
+    def update(self, **kwargs) -> None:
+        for key, value in kwargs.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+
+    def to_dict(self) -> dict:
+        return {
+            "long_context_cutoff": self.long_context_cutoff,
+            "force_long_context": self.force_long_context,
+            "max_iterations": self.max_iterations,
+        }
+
+    def from_dict(self, config: dict) -> None:
+        self.update(**config)
+
+
+class SkillV4:
+    name: str
+    source_message: str
+
+    python_name: str
+    docstring: str
+    code: str
+
+    def __init__(
+        self,
+        name: str,
+        source_message: str,
+        python_name: str,
+        docstring: str,
+        code: str,
+    ) -> None:
+        self.name = name
+        self.python_name = python_name
+        self.docstring = docstring
+        self.code = code
+        self.source_message = source_message
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "python_name": self.python_name,
+            "docstring": self.docstring,
+            "code": self.code,
+            "source_message": self.source_message,
+        }
+
+    def from_dict(self, skill: dict) -> None:
+        self.name = skill["name"]
+        self.python_name = skill["python_name"]
+        self.docstring = skill["docstring"]
+        self.code = skill["code"]
+        self.source_message = skill["source_message"]
+
+    def __str__(self) -> str:
+        return f"Skill: {self.name}\nPython name: {self.python_name}\nDocstring: {self.docstring}\nCode: {self.code}\nSource message: {self.source_message}"
+
+
+class FrameV4:
+    # general
+    instance_id: str
+    config: FrameConfigV4
+    client_profile: dict[str, Client]
+    errand_profile: dict[str, type[Errand]]
+    compilation_trace: Trace
+    execution_trace: Trace
+    max_iterations: int = 1024
+
+    # skills
+    skills: dict[str, SkillV4]
+
+    # context
+    tidings: dict[str, Tiding]
+    globals: dict[str, Any]
+    last_mid: int
+
+    def __init__(
+        self,
+        client_profile: dict[str, Client] | Client,
+        instance_id: str | None = None,
+        config: FrameConfigV4 | None = None,
+        errand_profile: dict[str, type[Errand]] | None = None,
+        compilation_trace: bool | str | Trace | None = None,
+        execution_trace: bool | str | Trace | None = None,
+    ) -> None:
+        self.instance_id = (
+            datetime.now().strftime("%Y%m%d_%H-%M-%S")
+            if instance_id is None
+            else instance_id
+        )
+        self.config = FrameConfigV4() if config is None else config
+
+        self.errand_profile = (
+            {**default_errand_profile, **errand_profile}
+            if errand_profile is not None
+            else {**default_errand_profile}
+        )
+        if isinstance(client_profile, Client):
+            self.client_profile = {
+                k: client_profile for k, _ in self.errand_profile.items()
+            }
+        elif isinstance(client_profile, dict):
+            self.client_profile = client_profile
+        else:
+            raise ValueError(f"Invalid client profile type: {type(client_profile)}")
+
+        self.compilation_trace = self.make_trace_from_arg(
+            path=f"./logs/{self.instance_id}_compilation.log",
+            trace_arg=compilation_trace,
+        )
+        self.execution_trace = self.make_trace_from_arg(
+            path=f"./logs/{self.instance_id}_execution.log", trace_arg=execution_trace
+        )
+
+        self.new_instance()
+
+    def get_chat_context_dict(self) -> dict:
+        """
+        Returns the chat context as a dictionary
+        """
+
+        filtered_system_globals = {
+            k: v
+            for k, v in self.globals.items()
+            if not k.startswith("__")
+            and not callable(v)
+            and type(v) in [float, int, str, bool, list, set, dict, tuple]
+        }
+        return {
+            "mid": self.last_mid,
+            "tidings": {k: v.to_dict() for k, v in self.tidings.items()},
+            "system_globals": filtered_system_globals,
+        }
+
+    def new_instance(self) -> None:
+        self.skills = {}
+        self.tidings = {}
+        self.globals = {"__messages": []}
+        self.last_mid = -1
+
+        exec("import math", {}, self.globals)
+        exec("from typing import *", {}, self.globals)
+        exec("from tavily import TavilyClient", {}, self.globals)
+        client = self.find_client_in_profile("language_model")
+
+        def language_model(prompt: str, pre_prompt: str = None) -> str:
+            """
+            A simple language model calling function that returns the prompt as a response.
+
+            Use the following guidelines to create effective prompts when calling the function `language_model`:
+            - Start with using pre_prompt to assign a role to the language model (e.g. "You are an expert report writer." or "You are a Python code generator.")
+            - Begin the prompt by asking the language model to perform a specific task (e.g. "Write a report on the current state of AI research based on the following CONTEXT." or "Generate a Python function that behaviour described in ASSIGNMENT.")
+            - Mention the parameters of the prompt in the prompt, i.e. if the prompt operates on a text, mention the name of the parameter (e.g. "CONTEXT" or "ASSIGNMENT") and the type of the parameter (e.g. "text", "list", "dictionary", etc.).
+            - Specify the expected output format (e.g. "Write a report in Markdown format. Do not output any other text." or "Generate a Python function that returns a list of numbers and enclose it in ``` and ```. Any text outside the code block will be ignored.")
+            - Provide the context or assignment in a clear and concise manner (.e.g "\n\nCONTEXT:\n <context>" or "\n\nASSIGNMENT:\n<assignment>"); use newlines to separate the parameters from the rest of the prompt.
+            - If you think the prompt might get long once the parameters are pasted into it, add a list of reminders, e.g. "Reminders:\n- Do not output any other text.\n- Output a report in Markdown format based on the CONTEXT given..."
+
+            Args:
+                prompt (str): The prompt to be sent to the language model.
+                pre_prompt (str, optional): An optional pre-prompt (also known as system prompt, can be used to assign an overarching role to the LM) to be sent before the main prompt.
+
+            Returns:
+                str: The response from the language model.
+            """
+            return client.run(pre_prompt, prompt)
+
+        if "language_model" not in self.skills:
+            self.skills["language_model"] = SkillV4(
+                name="language_model",
+                source_message="",
+                python_name="language_model",
+                docstring=language_model.__doc__,
+                code=language_model.__code__,
+            )
+        self.globals["language_model"] = language_model
+
+        self.execution_trace.write_separator()
+        self.execution_trace(
+            f"Creating new instance with id {self.instance_id} at {datetime.now()}"
+        )
+        self.execution_trace(
+            f"New instance created; skills, tidings, and globals erased"
+        )
+        self.execution_trace.write_separator()
+
+    # HIGH-LEVEL OUTPUT GENERATION CODE
+    def generate(
+        self, messages: list[dict], frame_config: FrameConfigV4 | None = None
+    ) -> str:
+        """
+        Generates a response to the given messages.
+        """
+        if frame_config is None:
+            frame_config = self.config
+
+        last_msg = messages[-1]
+        ret = self.process_message(
+            mid=last_msg["mid"],
+            message=last_msg["content"],
+            message_type=last_msg["type"],
+        )
+        return ret
+
+        # HIGH-LEVEL OUTPUT GENERATION CODE
+
+    def generate_with_notifications(
+        self, messages: list[dict], frame_config: FrameConfigV4 | None = None
+    ) -> Generator[dict, None, None]:
+        """
+        Generates a response to the given messages.
+        """
+        if frame_config is None:
+            frame_config = self.config
+
+        last_msg = messages[-1]
+        for notification in self.process_message(
+            mid=last_msg["mid"],
+            message=last_msg["content"],
+            message_type=last_msg["type"],
+            generate_not_return=True,
+        ):
+            yield notification
+
+    # MESSAGE HANDLING
+    def process_message(
+        self,
+        mid: int,
+        message: str,
+        message_type: str | None,
+        generate_not_return: bool = False,
+    ) -> Any | Generator[dict, None, None]:
+        """
+        message_type is one of "routine", "routine_skill", "query", "query_skill", "code", "code_skill", "data", "auto" (also representable as None)
+        """
+        if message.strip() == "":
+            raise ValueError("Empty message provided for instruction processing")
+        if message_type is None:
+            message_type = "auto"
+        self.allowed_message_types = [
+            "routine",
+            "routine_skill",
+            "query",
+            "query_skill",
+            "code",
+            "code_skill",
+            "data",
+            "auto",
+            "generating_routine",
+        ]
+        if message_type not in self.allowed_message_types:
+            allowed_message_types_str: str = "', '".join(self.allowed_message_types)
+            raise ValueError(
+                f"Invalid message type: '{message_type}'; must be one of '{allowed_message_types_str}'"
+            )
+
+        if message_type == "auto":
+            message_type = self.decide_message_type(message)
+
+        skills: list[SkillV4] | None = None
+        invocation_code: str | None = None
+        variable_descriptions: dict[str, str] | None = None
+
+        if message_type == "code":
+            skills, invocation_code, variable_descriptions = self.process_message_code(
+                mid, message, self.tidings
+            )
+        elif message_type == "code_skill":
+            skills = self.process_message_code_skill(
+                mid, message
+            )  # no tidings, skills are supposed to be pure functions
+        elif message_type == "routine":
+            skills, invocation_code, variable_descriptions = (
+                self.process_message_routine(mid, message, self.tidings)
+            )
+        elif message_type == "generating_routine":
+            if not generate_not_return:
+                raise ValueError(
+                    "Generating routine messages must be processed with generate_not_return=True"
+                )
+            skills, invocation_code, variable_descriptions = (
+                self.process_message_routine(
+                    mid, message, self.tidings, is_generating_routine=True
+                )
+            )
+        elif message_type == "data":
+            invocation_code = self.process_message_data(mid, message)
+            skills = []
+        else:
+            raise NotImplementedError(
+                f"Message type '{message_type}' not implemented yet"
+            )
+
+        self.log_compilation_result(mid, skills, invocation_code, variable_descriptions)
+
+        skill_capture_context = {}
+        for skill in skills:
+            exec(f"{skill.code}", self.globals, skill_capture_context)
+            self.skills[skill.name] = skill
+        for context_var, context_value in skill_capture_context.items():
+            if not context_var in self.globals:
+                self.globals[context_var] = context_value
+
+        execution_context = {
+            tiding.python_name: tiding.content for tiding in self.tidings.values()
+        }
+        __output = None
+        if invocation_code is not None:
+            if message_type != "generating_routine":
+                exec(invocation_code, self.globals, execution_context)
+                if "__output" in execution_context:
+                    __output = execution_context["__output"]
+                if "__vars" in execution_context:
+                    __vars = execution_context["__vars"]
+                    for var_name, var_value in __vars.items():
+                        self.tidings[var_name] = Tiding(
+                            natural_name=var_name,
+                            python_name=var_name,
+                            content=var_value,
+                            description=(
+                                variable_descriptions[var_name]
+                                if variable_descriptions is not None
+                                and var_name in variable_descriptions
+                                else ""
+                            ),
+                        )
+            else:
+                exec(invocation_code, self.globals, execution_context)
+                __generator = execution_context["__generator"]
+                __final: dict[str, Any] = {}
+                for notification in __generator:
+                    if notification["type"] == "final":
+                        __final = notification
+                    else:
+                        yield notification
+                if "modified_vars" in __final:
+                    for var_name, var_value in __final["modified_vars"].items():
+                        self.tidings[var_name] = Tiding(
+                            natural_name=var_name,
+                            python_name=var_name,
+                            content=var_value,
+                            description=(
+                                variable_descriptions[var_name]
+                                if variable_descriptions is not None
+                                and var_name in variable_descriptions
+                                else ""
+                            ),
+                        )
+
+        self.last_mid = mid
+
+        if not generate_not_return:
+            return __output
+
+    def decide_message_type(self, message: str) -> str:
+        """
+        Decides the message type based on the content of the message.
+
+        Returns one of "routine", "routine_skill", "query", "query_skill", "code", "code_skill", "data"
+        """
+        message_type_errand: Errand = self.find_errand_in_profile("message_type")()
+        message_type_client = self.find_client_in_profile("message_type")
+
+        message_type: str | None = message_type_errand.run(
+            runner=message_type_client,
+            args={"message": message},
+        )
+
+        if message_type is None or message_type not in self.allowed_message_types:
+            raise ValueError(
+                f"Message type could not be determined for message: '{message}'"
+            )
+
+        return message_type
+
+    # MESSAGE PROCESSING
+    def process_message_code(
+        self, mid: int, message: str, tidings: dict[str, Tiding]
+    ) -> tuple[list[SkillV4], str | None, dict[str, str] | None]:
+        """
+        Processes a code message and returns the corresponding skill(s), invocation code, and variable descriptions.
+        """
+        code_processing_errand: Errand = self.find_errand_in_profile(
+            "message_code_processing"
+        )()
+        code_processing_client = self.find_client_in_profile("message_code_processing")
+
+        # serialize tidings for prompt injection
+        serialized_tidings = "\n".join(
+            [f"{k}: {v.content}  # {v.description}" for k, v in tidings.items()]
+        )
+        code: str = code_processing_errand.run(
+            runner=code_processing_client,
+            args={"message": message, "tidings": serialized_tidings},
+        )
+        code = self.sanitize_code(code)
+
+        # replace the first occurence of code with f"message_{mid}_code"
+        code = code.replace("code", f"message_{mid}_code", 1)
+        docstring_addendum = f"\n\nThis function was generated to fulfill the intent of the user message with message id {mid}."
+
+        func_defs = self.extract_function_definitions(code)
+        skills = []
+        variable_descriptions: dict[str, str] | None = None
+        if func_defs:
+            func = func_defs[0]
+            func_code = func["code"].replace(
+                func["docstring"], func["docstring"] + docstring_addendum, 1
+            )
+            skills.append(
+                SkillV4(
+                    name=func["python_name"],
+                    source_message=message,
+                    python_name=func["python_name"],
+                    docstring=func["docstring"] + docstring_addendum,
+                    code=func_code,
+                )
+            )
+
+            # TODO: perhaps, in the future, let the user know that other functions are present but ignored
+
+            message_code_call_errand: Errand = self.find_errand_in_profile(
+                "message_code_call"
+            )()
+            message_code_call_client = self.find_client_in_profile("message_code_call")
+            invocation_code = message_code_call_errand.run(
+                runner=message_code_call_client,
+                args={
+                    "message": message,
+                    "code": skills[0].code,
+                    "tidings": serialized_tidings,
+                },
+            )
+
+            # Use MessageCodeVariablesErrand to get variable descriptions
+            message_code_variables_errand: Errand = self.find_errand_in_profile(
+                "message_code_variables"
+            )()
+            message_code_variables_client = self.find_client_in_profile(
+                "message_code_variables"
+            )
+            variable_descriptions_raw = message_code_variables_errand.run(
+                runner=message_code_variables_client,
+                args={
+                    "message": message,
+                    "code": skills[0].code,
+                    "tidings": serialized_tidings,
+                },
+            )
+            # Parse the output into a dict
+            variable_descriptions = {}
+            for line in variable_descriptions_raw.strip().splitlines():
+                if "#" in line:
+                    var, desc = line.split("#", 1)
+                    variable_descriptions[var.strip()] = desc.strip()
+
+            return skills, invocation_code, variable_descriptions
+        else:
+            return [], None, None
+
+    def process_message_code_skill(self, mid: int, message: str) -> list[SkillV4]:
+        """
+        Processes a code_skill message and returns the corresponding skill(s).
+        """
+        code_skill_processing_errand: Errand = self.find_errand_in_profile(
+            "message_code_skill_processing"
+        )()
+        code_skill_processing_client = self.find_client_in_profile(
+            "message_code_skill_processing"
+        )
+        code: str = code_skill_processing_errand.run(
+            runner=code_skill_processing_client,
+            args={"message": message},
+        )
+        code = self.sanitize_code(code)
+
+        docstring_addendum = f"\n\nThis function was generated to fulfill the intent of the user message with message id {mid}."
+
+        func_defs = self.extract_function_definitions(code)
+        skills = []
+        if func_defs:
+            for func in func_defs:
+                func_code = func["code"].replace(
+                    func["docstring"], func["docstring"] + docstring_addendum, 1
+                )
+                skills.append(
+                    SkillV4(
+                        name=func["python_name"],
+                        source_message=message,
+                        python_name=func["python_name"],
+                        docstring=func["docstring"] + docstring_addendum,
+                        code=func_code,
+                    )
+                )
+        return skills
+
+    def process_message_routine(
+        self,
+        mid: int,
+        message: str,
+        tidings: dict[str, Tiding],
+        is_generating_routine: bool = False,
+    ) -> tuple[list[SkillV4], str | None, dict[str, str] | None]:
+        """
+        Processes a routine message and returns the corresponding skill(s), invocation code, and variable descriptions.
+        """
+        routine_processing_errand: Errand = (
+            self.find_errand_in_profile("message_routine_processing")()
+            if not is_generating_routine
+            else self.find_errand_in_profile("message_generating_routine_processing")()
+        )
+        routine_processing_client = (
+            self.find_client_in_profile("message_routine_processing")
+            if not is_generating_routine
+            else self.find_client_in_profile("message_generating_routine_processing")
+        )
+
+        # Prepare skills and tidings for prompt injection
+        serialized_skills = "\n\n".join(
+            [f"function {k}\n---\n{v.docstring}" for k, v in self.skills.items()]
+        )
+        serialized_tidings = "\n".join(
+            [f"{k} = {v.content}  # {v.description}" for k, v in tidings.items()]
+        )
+        code: str = routine_processing_errand.run(
+            runner=routine_processing_client,
+            args={
+                "message": message,
+                "skills": serialized_skills,
+                "tidings": serialized_tidings,
+            },
+        )
+        code = self.sanitize_code(code)
+
+        # replace the first occurrence of code with f"message_{mid}_routine_code"
+        code = code.replace("code", f"message_{mid}_routine_code", 1)
+        docstring_addendum = f"\n\nThis function was generated to fulfill the intent of the user message with message id {mid}."
+
+        func_defs = self.extract_function_definitions(code)
+        skills = []
+        variable_descriptions: dict[str, str] | None = None
+        if func_defs:
+            func = func_defs[0]
+            func_code = func["code"].replace(
+                func["docstring"], func["docstring"] + docstring_addendum, 1
+            )
+            skills.append(
+                SkillV4(
+                    name=func["python_name"],
+                    source_message=message,
+                    python_name=func["python_name"],
+                    docstring=func["docstring"] + docstring_addendum,
+                    code=func_code,
+                )
+            )
+
+            # Generate invocation code using MessageRoutineCallErrand
+            message_routine_call_errand: Errand = (
+                self.find_errand_in_profile("message_routine_call")()
+                if not is_generating_routine
+                else self.find_errand_in_profile("message_generating_routine_call")()
+            )
+            message_routine_call_client = (
+                self.find_client_in_profile("message_routine_call")
+                if not is_generating_routine
+                else self.find_client_in_profile("message_generating_routine_call")
+            )
+            invocation_code = message_routine_call_errand.run(
+                runner=message_routine_call_client,
+                args={
+                    "message": message,
+                    "code": skills[0].code,
+                    "tidings": serialized_tidings,
+                },
+            )
+
+            # Generate variable descriptions using MessageRoutineVariablesErrand
+            message_routine_variables_errand: Errand = self.find_errand_in_profile(
+                "message_routine_variables"
+            )()
+            message_routine_variables_client = self.find_client_in_profile(
+                "message_routine_variables"
+            )
+            variable_descriptions_raw = message_routine_variables_errand.run(
+                runner=message_routine_variables_client,
+                args={
+                    "message": message,
+                    "code": skills[0].code,
+                    "tidings": serialized_tidings,
+                },
+            )
+            # Parse the output into a dict
+            variable_descriptions = {}
+            for line in variable_descriptions_raw.strip().splitlines():
+                if "#" in line:
+                    var, desc = line.split("#", 1)
+                    variable_descriptions[var.strip()] = desc.strip()
+
+            return skills, invocation_code, variable_descriptions
+        else:
+            return [], None, None
+
+    def process_message_data(self, mid: int, message: str) -> str:
+        """
+        Processes a data message and returns the corresponding Python code that, when executed, loads variables into memory.
+        """
+        data_processing_errand: Errand = self.find_errand_in_profile(
+            "message_data_processing"
+        )()
+        data_processing_client = self.find_client_in_profile("message_data_processing")
+
+        code: str = data_processing_errand.run(
+            runner=data_processing_client,
+            args={"message": message},
+        )
+        code = self.sanitize_code(code)
+        return code
+
+    # MISC
+    def make_trace_from_arg(
+        self, path: str, trace_arg: bool | str | Trace | None = None
+    ) -> Trace:
+        if trace_arg is None:
+            return Trace(None)
+        if isinstance(trace_arg, Trace):
+            return trace_arg
+        if isinstance(trace_arg, bool):
+            if trace_arg is True:
+                return Trace(path)
+            else:
+                return Trace(None)
+        if isinstance(trace_arg, str):
+            if trace_arg == "stdout":
+                return Trace(None, copy_into_stdout=True)
+            if trace_arg == "file_and_stdout":
+                return Trace(path, copy_into_stdout=True)
+            else:
+                raise ValueError(f"Invalid value for trace: {trace_arg}")
+
+    def log_compilation_result(
+        self,
+        mid: int,
+        skills: list[SkillV4] | None,
+        invocation_code: str | None,
+        variable_descriptions: dict[str, str] | None,
+    ) -> None:
+        self.compilation_trace.write_separator()
+        self.compilation_trace(f"Compiled message {mid} at {datetime.now()}")
+        if invocation_code is not None:
+            self.compilation_trace(f"Invocation code: {invocation_code}")
+        if variable_descriptions is not None:
+            self.compilation_trace(f"Variable descriptions: {variable_descriptions}")
+
+        if skills is not None:
+            for skill in skills:
+                self.compilation_trace("*" * 20)
+                self.compilation_trace(f"Skill name: {skill.name}")
+                self.compilation_trace(f"Python name: {skill.python_name}")
+                self.compilation_trace(f"Docstring:\n{skill.docstring}")
+                self.compilation_trace("-" * 20)
+                self.compilation_trace(f"Code:\n{skill.code}")
+                self.compilation_trace("-" * 20)
+                self.compilation_trace(f"Source message:\n{skill.source_message}")
+
+        self.compilation_trace.write_separator()
+
+    def find_errand_in_profile(self, designation: str) -> type[Errand]:
+        if designation in self.errand_profile:
+            return self.errand_profile[designation]
+        raise ValueError(
+            f"Errand choice with designation '{designation}' not found in the errand profile"
+        )
+
+    def find_client_in_profile(self, designation: str) -> Client:
+        if designation in self.client_profile:
+            return self.client_profile[designation]
+        raise ValueError(
+            f"Client choice with designation '{designation}' not found in the client profile"
+        )
+
+    def extract_function_definitions(self, code: str) -> list[dict[str, Any]]:
+        """
+        Parses the given Python code and returns a list of dictionaries, each containing:
+        - python_name: the function name
+        - args: a list of argument names
+        - docstring: the function docstring (or None)
+        - code: the full source code of the function, including the signature
+        Only top-level (module-level) functions are extracted; nested functions are ignored.
+        """
+        results = []
+        try:
+            tree = ast.parse(code)
+        except Exception as e:
+            return []
+
+        # Helper to get source code for a node
+        def get_source_segment(node):
+            try:
+                return ast.get_source_segment(code, node)
+            except Exception:
+                lines = code.splitlines()
+                if hasattr(node, "lineno") and hasattr(node, "end_lineno"):
+                    return "\n".join(lines[node.lineno - 1 : node.end_lineno])
+                return None
+
+        # Only consider top-level functions (direct children of Module)
+        for node in tree.body:
+            if isinstance(node, ast.FunctionDef):
+                func_name = node.name
+                args = [arg.arg for arg in node.args.args]
+                docstring = ast.get_docstring(node)
+                func_code = get_source_segment(node)
+                results.append(
+                    {
+                        "python_name": func_name,
+                        "args": args,
+                        "docstring": docstring,
+                        "code": func_code,
+                    }
+                )
+        return results
+
+    def sanitize_code(self, code: str) -> str:
+        """
+        Sanitizes the code by removing ```python and ``` tags. Note that the code might also start with ``` and end with ```.
+        """
+        # Remove the first and last lines if they are empty
+        lines = code.splitlines()
+        if len(lines) > 0 and lines[0].strip() == "":
+            lines = lines[1:]
+        if len(lines) > 0 and lines[-1].strip() == "":
+            lines = lines[:-1]
+
+        # Remove the first and last lines if they are ```python or ```
+        if len(lines) > 0 and (
+            lines[0].strip() == "```python" or lines[0].strip() == "```"
+        ):
+            lines = lines[1:]
+        if len(lines) > 0 and (
+            lines[-1].strip() == "```" or lines[-1].strip() == "```python"
+        ):
+            lines = lines[:-1]
+
+        return "\n".join(lines)

backend/frame/prompts/udr_minimal/0.code_skill.py

@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+def send_message(type, description, **kwargs):
+    """
+    Sends a message by appending it to the global `__messages` list.
+
+    This function creates a message dictionary with a specified type and description,
+    along with any additional keyword arguments provided. The constructed message is
+    then added to the global `__messages` list for further processing or logging.
+
+    Args:
+        type (str): The type of the message (e.g., "error", "info", "warning").
+        description (str): A brief description of the message content.
+        **kwargs: Additional key-value pairs to include in the message dictionary.
+
+    Raises:
+        NameError: If the global variable `__messages` is not defined.
+
+    Example:
+        send_message(
+            type="info",
+            description="Process completed successfully",
+            report="Reporting information" # optional, added for this particular example
+        )
+    """
+    global __messages
+    message = {"type": type, "description": description, **kwargs}
+    __messages.append(message)

backend/frame/prompts/udr_minimal/1.code_skill.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+def perform_search(search_phrase: str):
+    """
+    Performs a search using the Tavily API and returns a list of search result objects.
+
+    Args:
+        search_phrase (str): The phrase to search for using the Tavily API.
+
+    Returns:
+        List[Dict[str, Any]]: A list of search result dictionaries obtained from the Tavily API. Each dictionary has 'content' field with text retrieved from the result, and a 'url' field that keeps the url of the search result.
+
+    Raises:
+        TavilyClientError: If there is an issue with the Tavily API client or the search request.
+        KeyError: If the expected 'results' key is missing in the search response.
+
+    """
+    from tavily import TavilyClient
+
+    client = TavilyClient(api_key="tvly-dev-XXXX")
+    search_response = client.search(search_phrase, include_raw_content=True)
+    return search_response["results"]

backend/frame/prompts/udr_minimal/2.auto.txt

@@ -0,0 +1,4 @@
+The following is the prompt data to be used in later procedures.
+
+PROMPT:
+Produce a comprehensive report on the major Christian events that took place this year between the 20th and 22nd of April 2025.

backend/frame/prompts/udr_minimal/3.auto.txt

@@ -0,0 +1,11 @@
+1. Send a message of type "prompt_received" with description saying what PROMPT has been received, e.g. "Received research request: {PROMPT}"
+2. Send a message of type "prompt_analysis_started", with description indicating that we are now analyzing the research request.
+3. Take the PROMPT and ask a language model to produce 3 search phrases that could help with retrieving results from search engine for the purpose of compiling a report the user asks for in the PROMPT. The search phrases should be simple and objective, e.g. "important events 1972" or "energy consumption composition in India today". Use a long prompt for the model that describes in detail what is supposed to be performed and the expected output format. Instruct the model to return the search phrases on one line each. Tell the model not to output any other text -- just the newline-separated phrases. Then, parse the output of the language model line by line and save the resulting search phrases as "phrases" for further research, skipping over empty lines.
+4. Send a message of type "prompt_analysis_completed", with a description saying as much.
+5. For each phrase in phrases output by step 3., perform the following:
+    - Send a message of type "search_started", with the description indicating what search phrase we are using for the search, e.g. "Searching for phrase '{phrase}'"
+    - Perform search with the phrase. Once the search returns some results, append their contents to CONTEXT one by one, separating them by double newlines from what is already present in the CONTEXT.
+6. Send a message with type "report_building", with the description indicating that the report is being built.
+7. Take CONTEXT. Call the language model, instructing it to take CONTEXT (to be appended into the LM call) and produce a deep research report on the topic requested in PROMPT. The resulting report should go into detail wherever possible, rely only on the information available in CONTEXT, address the instruction given in the PROMPT, and be formatted in Markdown. This is to be communicated in the prompt. Do not shy away from using long, detailed and descriptive prompts! Tell the model not to output any other text, just the report. The result produced by the language model is to be called REPORT.
+8. Send a message with type "report_done", indicating that the report has been completed. Add "report" as a field containing the REPORT to be an additional payload to the message.
+9. Output the REPORT.

backend/frame/prompts/udr_minimal_generating/0.code_skill.py

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+def perform_search(search_phrase: str):
+    """
+    Performs a search using the Tavily API and returns a list of search result objects.
+
+    Args:
+        search_phrase (str): The phrase to search for using the Tavily API.
+
+    Returns:
+        List[Dict[str, Any]]: A list of search result dictionaries obtained from the Tavily API. Each dictionary has 'content' field with text retrieved from the result, and a 'url' field that keeps the url of the search result.
+
+    Raises:
+        TavilyClientError: If there is an issue with the Tavily API client or the search request.
+        KeyError: If the expected 'results' key is missing in the search response.
+
+    """
+    from tavily import TavilyClient
+
+    client = TavilyClient(api_key="tvly-dev-XXXX")
+    search_response = client.search(search_phrase, include_raw_content=True)
+    return search_response["results"]

backend/frame/prompts/udr_minimal_generating/1.auto.txt

@@ -0,0 +1,4 @@
+The following is the prompt data to be used in later procedures.
+
+PROMPT:
+Produce a comprehensive report on the major Christian events that took place this year between the 20th and 22nd of April 2025.

backend/frame/prompts/udr_minimal_generating/2.routine_generating.txt

@@ -0,0 +1,15 @@
+1. Send a notification of type "prompt_received" with description saying what PROMPT has been received, e.g. "Received research request: {PROMPT}"
+2. Send a notification of type "prompt_analysis_started", with description indicating that we are now analyzing the research request.
+3. Take the PROMPT and ask a language model to produce 3 search phrases that could help with retrieving results from search engine for the purpose of compiling a report the user asks for in the PROMPT. The search phrases should be simple and objective, e.g. "important events 1972" or "energy consumption composition in India today". Use a long prompt for the model that describes in detail what is supposed to be performed and the expected output format. Instruct the model to return the search phrases on one line each. Tell the model not to output any other text -- just the newline-separated phrases. Then, parse the output of the language model line by line and save the resulting search phrases as "phrases" for further research, skipping over empty lines.
+4. Send a notification of type "prompt_analysis_completed", with a description saying as much.
+4.1 Send a notification of type "task_analysis_completed", informing the user that the search plan has been completed and informing them how many search phrases will be invoked, e.g.  "Search planning completed. Will be searching through {len(topics)}+ terms."
+5. For each phrase in phrases output by step 3., perform the following:
+    - Send a notification of type "search_started", with the description indicating what search phrase we are using for the search, e.g. "Searching for phrase '{phrase}'"
+    - Perform search with the phrase.
+    - Once the search returns some results, append their contents to CONTEXT one by one, separating them by double newlines from what is already present in the CONTEXT.
+    - Send a notification of type "search_result_processing_completed", indicating in its description that the search results for term {term} have been processed.
+6. Send a notification to the user with type "research_completed", indicating that the "Research phase is now completed.".
+7. Send a notification with type "report_building", with the description indicating that the report is being built.
+8. Take CONTEXT. Call the language model, instructing it to take CONTEXT (to be appended into the LM call) and produce a deep research report on the topic requested in PROMPT. The resulting report should go into detail wherever possible, rely only on the information available in CONTEXT, address the instruction given in the PROMPT, and be formatted in Markdown. This is to be communicated in the prompt. Do not shy away from using long, detailed and descriptive prompts! Tell the model not to output any other text, just the report. The result produced by the language model is to be called REPORT.
+9. Send a notification with type "report_done", indicating that the report has been completed. Add "report" as a field containing the REPORT to be an additional payload to the notification.
+10. Output the REPORT.

backend/frame/routines.py

@@ -0,0 +1,131 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import importlib.util
+import json
+import sys
+import types
+
+import docstring_parser
+
+
+def import_from_path(module_name, file_path):
+    """Import a module given its name and file path."""
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class Routine:
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        parameters: dict[str, str],
+        fn: callable,
+        returns: dict[str, str] | None = None,
+        module: str | None = None,
+        source_file: str | None = None,
+    ) -> None:
+        self.name: str = name
+        self.description: str = description
+        self.parameters: dict[str, dict[str, str]] = parameters
+        self.returns: dict[str, str] | None = returns
+        self.fn = fn
+
+        self.module: str | None = module
+        self.source_file: str | None = source_file
+
+    def __str__(self) -> str:
+        ret = "Name: " + self.name + "\n"
+        ret += "Description: " + self.description + "\n"
+        ret += "Parameters:\n"
+        for key, props in self.parameters.items():
+            ret += f"  {key}:\n"
+            for prop, value in props.items():
+                ret += f"    {prop}: {value}\n"
+        return ret
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {"type": "object", "properties": self.parameters},
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=4)
+
+
+class RoutineRegistry:
+    def __init__(self, routines: list[Routine] | None = None) -> None:
+        self.routines: list[Routine] = routines if routines is not None else []
+
+    def add_routine(self, routine: Routine) -> None:
+        self.routines.append(routine)
+
+    def remove_routine(self, routine: Routine) -> None:
+        self.routines.remove(routine)
+
+    def get_routine_of_name(self, name: str) -> Routine:
+        return next(
+            (
+                routine
+                for routine in self.routines
+                if routine.name.lower() == name.lower()
+            ),
+            None,
+        )
+
+    def to_list(self) -> list[dict]:
+        return [routine.to_dict() for routine in self.routines]
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_list(), indent=4)
+
+    def load_from_file(self, module_name: str, file_path: str) -> None:
+        module = import_from_path(module_name, file_path)
+        for name, obj in module.__dict__.items():
+            if type(obj) == types.FunctionType:
+                doc = docstring_parser.parse(obj.__doc__)
+                parameters = {
+                    param.arg_name: {
+                        "type": param.type_name,
+                        "description": param.description,
+                    }
+                    for param in doc.params
+                }
+                returns = {
+                    "type": doc.returns.type_name,
+                    "description": doc.returns.description,
+                }
+                self.add_routine(
+                    Routine(
+                        name,
+                        doc.short_description
+                        + "\n"
+                        + (
+                            doc.long_description
+                            if doc.long_description is not None
+                            else ""
+                        ),
+                        parameters,
+                        obj,
+                        returns,
+                        module_name,
+                        file_path,
+                    )
+                )

backend/frame/tidings.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from typing import Any
+
+
+class Tiding:
+    def __init__(
+        self, natural_name: str, python_name: str, description: str, content: Any
+    ) -> None:
+        self.natural_name = natural_name
+        self.python_name = python_name
+        self.description = description
+        self.content = content
+
+    def __str__(self) -> str:
+        return f"Natural name: {self.natural_name}\nPython name: {self.python_name}\nDescription: {self.description}\nContent: {self.content}"
+
+    def to_dict(self) -> dict:
+        return {
+            "natural_name": self.natural_name,
+            "python_name": self.python_name,
+            "description": self.description,
+            "content": self.content,
+            "type": type(self.content).__name__,
+        }
+
+    def from_dict(self, tiding: dict) -> None:
+        self.natural_name = tiding["natural_name"]
+        self.python_name = tiding["python_name"]
+        self.description = tiding["description"]
+        self.content = tiding["content"]

backend/frame/trace.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+import sys
+from typing import Callable
+
+
+class Trace:
+    def __init__(
+        self,
+        path: str | None = None,
+        copy_into_stdout: bool = False,
+        hook: Callable = None,
+    ) -> None:
+        self.path = path
+        self.entries = []
+        self.copy_into_stdout = copy_into_stdout
+        self.hook = hook
+
+        # set self.file to a new file if path is not None or to stdout if it is None
+        self.file = open(path, "w") if path is not None else open(os.devnull, "w")
+
+    def write(self, entry: str) -> None:
+        self.entries.append(entry)
+        print(entry, file=self.file, flush=True)
+        if self.copy_into_stdout:
+            print(entry, file=sys.stdout, flush=True)
+        if self.hook is not None:
+            self.hook(entry)
+
+    def close(self) -> None:
+        self.file.close()
+
+    def __call__(self, *args) -> None:
+        for arg in args:
+            self.write(str(arg))
+
+    def write_separator(self) -> None:
+        self.write("#" * 80)

backend/insert_license.py

@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+from typing import List
+
+def add_header_to_python_files(directory_path, header_content, extensions: List[str] = [".py"]):
+    """
+    Inserts a specified header at the beginning of every .py file
+    in the given directory and its subdirectories.
+
+    Args:
+        directory_path (str): The path to the directory to process.
+        header_content (str): The content of the header to insert.
+                              Ensure it includes newlines for proper formatting.
+    """
+    for root, _, files in os.walk(directory_path):
+        for file_name in files:
+            if file_name == '.venv':
+                continue
+            for extension in extensions:
+                if file_name.endswith(extension):
+                    file_path = os.path.join(root, file_name)
+                    try:
+                        with open(file_path, 'r+', encoding='utf-8') as f:
+                            original_content = f.read()
+                            if original_content.startswith(header_content):
+                                print(f"Header already exists in: {file_path}")
+                                continue
+                            f.seek(0)  # Move cursor to the beginning of the file
+                            f.write(header_content + original_content)
+                        print(f"Header added to: {file_path}")
+                    except IOError as e:
+                        print(f"Error processing {file_path}: {e}")
+
+if __name__ == "__main__":
+    target_directory = "../frontend"  # Replace with your target directory
+    
+    # Define your header content here. Use triple quotes for multi-line strings.
+    # Ensure a newline character at the end of the header for separation.
+    custom_header = """/*
+ * SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+"""
+
+    add_header_to_python_files(target_directory, custom_header, extensions=[".js", ".ts", ".tsx", ".jsx", ".css"])

backend/items.py

@@ -0,0 +1,115 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Data persistence utilities for the Universal Deep Research Backend (UDR-B).
+
+This module provides functions for storing and loading research artifacts,
+events, and other data in JSONL format for easy processing and analysis.
+"""
+
+import json
+import os
+from typing import Any, Dict, List
+
+
+def store_items(items: List[Dict[str, Any]], filepath: str) -> None:
+    """
+    Stores a list of items line by line in a file, with proper string escaping.
+    Each item is stored as a JSON string on a separate line.
+
+    Args:
+        items: List of dictionaries to store
+        filepath: Path to the file where items will be stored
+
+    Example:
+        store_items([
+            {"type": "event1", "message": "Hello \"world\""},
+            {"type": "event2", "message": "Line\nbreak"}
+        ], "events.jsonl")
+    """
+    # Create directory if it doesn't exist
+    os.makedirs(os.path.dirname(filepath), exist_ok=True)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        for item in items:
+            # Convert dictionary to JSON string and write with newline
+            json_str = json.dumps(item, ensure_ascii=False)
+            f.write(json_str + "\n")
+
+
+def load_items(filepath: str) -> List[Dict[str, Any]]:
+    """
+    Loads items from a file where each line is a JSON string.
+
+    Args:
+        filepath: Path to the file containing the items
+
+    Returns:
+        List of items loaded from the file
+
+    Example:
+        items = load_items("events.jsonl")
+        for item in items:
+            print(item["type"], item["message"])
+    """
+    if not os.path.exists(filepath):
+        return []
+
+    items = []
+    with open(filepath, "r", encoding="utf-8") as f:
+        for line in f:
+            if line.strip():  # Skip empty lines
+                item = json.loads(line)
+                items.append(item)
+    return items
+
+
+def register_item(filepath: str, item: Dict[str, Any]) -> None:
+    """
+    Appends a single item to the specified file.
+    Creates the file and its directory if they don't exist.
+
+    Args:
+        filepath: Path to the file where the item will be appended
+        item: Dictionary to append to the file
+
+    Example:
+        register_item(
+            "events.jsonl",
+            {"type": "event3", "message": "New event"}
+        )
+    """
+    # Create directory if it doesn't exist
+    os.makedirs(os.path.dirname(filepath), exist_ok=True)
+
+    # Append the item to the file
+    with open(filepath, "a", encoding="utf-8") as f:
+        json_str = json.dumps(item, ensure_ascii=False)
+        f.write(json_str + "\n")
+
+
+def find_item_by_type(filepath: str, item_type: str) -> Dict[str, Any]:
+    """
+    Finds an item by its type in the specified file.
+
+    Args:
+        filepath: Path to the file containing the items
+        item_type: Type of the item to find
+
+    Returns:
+        Item found in the file
+    """
+    items = load_items(filepath)
+    return next((item for item in items if item["type"] == item_type), None)

backend/launch_server.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# Universal Deep Research Backend (UDR-B) - Server Launch Script
+# This script launches the FastAPI server with proper configuration
+
+# Load environment variables if .env file exists
+if [ -f ".env" ]; then
+    echo "Loading environment variables from .env file..."
+    export $(cat .env | grep -v '^#' | xargs)
+fi
+
+# Set default values if not provided
+HOST=${HOST:-0.0.0.0}
+PORT=${PORT:-8000}
+LOG_LEVEL=${LOG_LEVEL:-info}
+
+echo "Starting Universal Deep Research Backend (UDR-B)..."
+echo "Host: $HOST"
+echo "Port: $PORT"
+echo "Log Level: $LOG_LEVEL"
+
+# Launch the server
+uvicorn main:app \
+    --reload \
+    --env-file .env \
+    --access-log \
+    --log-level=$LOG_LEVEL \
+    --host $HOST \
+    --port $PORT \
+    > uvicorn_main.txt 2>&1 & 
+
+# Wait a moment for the process to start
+sleep 2
+
+# Find the uvicorn process ID using ps and grep
+PID=$(ps aux | grep "uvicorn main:app" | grep -v grep | awk '{print $2}' | head -1)
+
+if [ -n "$PID" ]; then
+    echo "Server started with PID: $PID"
+    echo "To stop the server, run: kill $PID"
+else
+    echo "Warning: Could not find uvicorn process ID"
+fi
+
+# Disown the process so it continues running after the script exits
+disown $!
+
+echo "Server started in background. Check uvicorn_main.txt for logs."
+echo "API available at: http://$HOST:$PORT"

backend/main.py

@@ -0,0 +1,471 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Universal Deep Research Backend (UDR-B) - FastAPI Application
+
+This module provides the main FastAPI application for the Universal Deep Research Backend,
+offering intelligent research and reporting capabilities through streaming APIs.
+"""
+
+import asyncio
+import json
+import os
+import random
+from datetime import datetime
+from typing import Any, AsyncGenerator, Dict, Optional
+
+import uvicorn
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from uvicorn.config import LOGGING_CONFIG
+
+import items
+
+# Import configuration
+from config import get_config
+from frame.clients import Client, HuggingFaceClient, OpenAIClient
+from frame.harness4 import FrameConfigV4, FrameV4
+from frame.trace import Trace
+from scan_research import do_reporting as real_reporting
+from scan_research import do_research as real_research
+from scan_research import generate_session_key
+from scan_research_dry import do_reporting as dry_reporting
+from scan_research_dry import do_research as dry_research
+
+# Get configuration
+config = get_config()
+
+app = FastAPI(
+    title="Universal Deep Research Backend API",
+    description="Intelligent research and reporting service using LLMs and web search",
+    version="1.0.0",
+)
+
+# Configure logging
+LOGGING_CONFIG["formatters"]["default"][
+    "fmt"
+] = "%(asctime)s [%(name)s] %(levelprefix)s %(message)s"
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[config.cors.frontend_url],  # Frontend URL from config
+    allow_credentials=config.cors.allow_credentials,
+    allow_methods=config.cors.allow_methods,
+    allow_headers=config.cors.allow_headers,
+)
+
+
+class Message(BaseModel):
+    text: str
+
+
+class ResearchRequest(BaseModel):
+    dry: bool = False
+    session_key: Optional[str] = None
+    start_from: str = "research"
+    strategy_id: Optional[str] = None
+    strategy_content: Optional[str] = None
+    prompt: Optional[str] = None
+    mock_directory: str = "mock_instances/stocks_24th_3_sections"
+
+
+@app.get("/")
+async def root():
+    return {
+        "message": "The Deep Research Backend is running. Use the /api/research endpoint to start a new research session."
+    }
+
+
+def build_events_path(session_key: str) -> str:
+    return f"instances/{session_key}.events.jsonl"
+
+
+def make_message(
+    event: Dict[str, Any],
+    session_key: str | None = None,
+    timestamp_the_event: bool = True,
+) -> str:
+    if timestamp_the_event:
+        event = {**event, "timestamp": datetime.now().isoformat()}
+
+    if session_key:
+        items.register_item(build_events_path(session_key), event)
+
+    return json.dumps({"event": event, "session_key": session_key}) + "\n"
+
+
+@app.post("/api/research")
+async def start_research(request: ResearchRequest):
+    """
+    Start or continue a research process and stream the results using JSON streaming.
+    
+    This endpoint initiates a comprehensive research workflow that includes:
+    - Query analysis and topic extraction
+    - Web search using Tavily API
+    - Content filtering and relevance scoring
+    - Report generation using LLMs
+    
+    The response is streamed as Server-Sent Events (SSE) with real-time progress updates.
+    
+    Args:
+        request (ResearchRequest): The research request containing:
+            - dry (bool): Use mock data for testing (default: False)
+            - session_key (str, optional): Existing session to continue
+            - start_from (str): "research" or "reporting" phase
+            - prompt (str): Research query (required for research phase)
+            - mock_directory (str): Directory for mock data
+    
+    Returns:
+        StreamingResponse: Server-Sent Events stream with research progress
+        
+    Raises:
+        HTTPException: 400 if request parameters are invalid
+        
+    Example:
+        ```bash
+        curl -X POST http://localhost:8000/api/research \\
+          -H "Content-Type: application/json" \\
+          -d '{
+            "prompt": "What are the latest developments in quantum computing?",
+            "start_from": "research"
+          }'
+        ```
+    """
+    # Validate request parameters
+    if request.start_from not in ["research", "reporting"]:
+        raise HTTPException(
+            status_code=400,
+            detail="start_from must be either 'research' or 'reporting'",
+        )
+
+    if request.start_from == "reporting" and not request.session_key:
+        raise HTTPException(
+            status_code=400,
+            detail="session_key is required when starting from reporting phase",
+        )
+
+    if request.start_from == "research" and not request.prompt:
+        raise HTTPException(
+            status_code=400,
+            detail="prompt is required when starting from research phase",
+        )
+
+    # Use configured mock directory
+    mock_dir = request.mock_directory or config.research.mock_directory
+
+    # Choose implementation
+    research_impl = (
+        (lambda session_key, prompt: dry_research(session_key, prompt, mock_dir))
+        if request.dry
+        else real_research
+    )
+    reporting_impl = (
+        (lambda session_key: dry_reporting(session_key, mock_dir))
+        if request.dry
+        else real_reporting
+    )
+
+    # Generate or use provided session key
+    session_key = request.session_key or generate_session_key()
+
+    # Prepare generators
+    research_gen = (
+        research_impl(session_key, request.prompt)
+        if request.start_from == "research"
+        else None
+    )
+    reporting_gen = reporting_impl(session_key)
+
+    return StreamingResponse(
+        stream_research_events(
+            research_gen, reporting_gen, request.start_from == "research", session_key
+        ),
+        media_type="application/x-ndjson",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "Content-Encoding": "none",
+        },
+    )
+
+
+async def stream_research_events(
+    research_fn: AsyncGenerator[Dict[str, Any], None],
+    reporting_fn: AsyncGenerator[Dict[str, Any], None],
+    do_research: bool,
+    session_key: str,
+) -> AsyncGenerator[str, None]:
+    """
+    Stream research or reporting events using JSON streaming format.
+
+    Args:
+        research_fn: Research phase generator
+        reporting_fn: Reporting phase generator
+        do_research: Whether to run research phase
+        session_key: Session identifier
+
+    Yields:
+        JSON formatted event strings, one per line
+    """
+    try:
+        yield make_message(
+            {
+                "type": "started",
+                "description": "Waking up the Deep Research Backend",
+            },
+            session_key,
+        )
+
+        error_event_encountered: bool = False
+        if do_research:
+            async for event in research_fn:
+                if event["type"] == "error":
+                    error_event_encountered = True
+                yield make_message(event, session_key)
+
+        if not error_event_encountered:
+            async for event in reporting_fn:
+                yield make_message(event, session_key)
+
+            # Send completion message
+            yield make_message(
+                {
+                    "type": "completed",
+                    "description": "Research and reporting completed",
+                },
+                session_key,
+            )
+    except asyncio.CancelledError:
+        # Send cancellation message before propagating the exception
+        yield make_message(
+            {
+                "type": "cancelled",
+                "description": "Research was cancelled",
+            },
+            session_key,
+        )
+        raise
+
+
+@app.post("/api/research2")
+async def start_research2(request: ResearchRequest):
+    # Validate request parameters
+    if request.start_from not in ["research"]:
+        raise HTTPException(status_code=400, detail="start_from must be 'research'")
+
+    if request.start_from == "research" and not request.prompt:
+        raise HTTPException(
+            status_code=400,
+            detail="prompt is required when starting from research phase",
+        )
+
+    # Generate or use provided session key
+    session_key = generate_session_key()
+
+    if request.strategy_id is None or request.strategy_id == "default":
+        # Validate request parameters
+        if request.start_from not in ["research", "reporting"]:
+            raise HTTPException(
+                status_code=400,
+                detail="start_from must be either 'research' or 'reporting'",
+            )
+
+        if request.start_from == "reporting" and not request.session_key:
+            raise HTTPException(
+                status_code=400,
+                detail="session_key is required when starting from reporting phase",
+            )
+
+        if request.start_from == "research" and not request.prompt:
+            raise HTTPException(
+                status_code=400,
+                detail="prompt is required when starting from research phase",
+            )
+
+        # Choose implementation
+        research_impl = (
+            (
+                lambda session_key, prompt: dry_research(
+                    session_key, prompt, "mock_instances/stocks_24th_3_sections"
+                )
+            )
+            if request.dry
+            else real_research
+        )
+        reporting_impl = (
+            (
+                lambda session_key: dry_reporting(
+                    session_key, "mock_instances/stocks_24th_3_sections"
+                )
+            )
+            if request.dry
+            else real_reporting
+        )
+
+        # Generate or use provided session key
+        session_key = request.session_key or generate_session_key()
+
+        # Prepare generators
+        research_gen = (
+            research_impl(session_key, request.prompt)
+            if request.start_from == "research"
+            else None
+        )
+        reporting_gen = reporting_impl(session_key)
+
+        return StreamingResponse(
+            stream_research_events(
+                research_gen,
+                reporting_gen,
+                request.start_from == "research",
+                session_key,
+            ),
+            media_type="application/x-ndjson",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Content-Encoding": "none",
+            },
+        )
+
+    return StreamingResponse(
+        stream_research2_events(
+            session_key, request.prompt, request.strategy_id, request.strategy_content
+        ),
+        media_type="application/x-ndjson",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "Content-Encoding": "none",
+        },
+    )
+
+
+async def stream_research2_events(
+    session_key: str, prompt: str, strategy_id: str, strategy_content: str
+) -> AsyncGenerator[str, None]:
+    try:
+        yield make_message(
+            {
+                "type": "started",
+                "description": "Waking up the Universal Deep Research Backend",
+            },
+            session_key,
+        )
+
+        # Set the random seed from configuration
+        random.seed(config.research.random_seed)
+
+        # Set trace filename using configuration
+        comm_trace_timestamp: str = datetime.now().strftime("%Y%m%d_%H-%M-%S")
+        comm_trace_filename = (
+            f"{config.logging.log_dir}/comms_{comm_trace_timestamp}.log"
+        )
+        comm_trace = Trace(
+            comm_trace_filename, copy_into_stdout=config.logging.copy_into_stdout
+        )
+
+        client: Client = OpenAIClient(
+            base_url="https://integrate.api.nvidia.com/v1",
+            model="nvdev/meta/llama-3.1-70b-instruct",
+            trace=comm_trace,
+        )
+
+        frame_config = FrameConfigV4(
+            long_context_cutoff=config.frame.long_context_cutoff,
+            force_long_context=config.frame.force_long_context,
+            max_iterations=config.frame.max_iterations,
+            interaction_level=config.frame.interaction_level,
+        )
+        harness = FrameV4(
+            client_profile=client,
+            errand_profile={},
+            compilation_trace=True,
+            execution_trace="file_and_stdout",
+        )
+
+        messages = []
+        preamble_files = [
+            "frame/prompts/udr_minimal_generating/0.code_skill.py",
+        ]
+        for path in preamble_files:
+            type = path.split(".")[-2]
+            with open(path, "r") as f:
+                messages.append(
+                    {
+                        "mid": len(messages),
+                        "role": "user",
+                        "content": f.read(),
+                        "type": type,
+                    }
+                )
+
+        messages.append(
+            {
+                "mid": len(messages),
+                "role": "user",
+                "content": "The following is the prompt data to be used in later procedures.\n\nPROMPT:\n"
+                + prompt,
+                "type": "data",
+            }
+        )
+
+        messages.append(
+            {
+                "mid": len(messages),
+                "role": "user",
+                "content": strategy_content,
+                "type": "generating_routine",
+            }
+        )
+
+        for i in range(len(messages)):
+            messages_so_far = messages[: i + 1]
+            yield make_message(
+                {
+                    "type": "generic",
+                    "description": "Processing agentic instructions: "
+                    + str(i + 1)
+                    + " of "
+                    + str(len(messages)),
+                },
+                session_key,
+            )
+            for notification in harness.generate_with_notifications(
+                messages=messages_so_far,
+                frame_config=frame_config,
+            ):
+                yield make_message(notification, session_key)
+
+        yield make_message(
+            {
+                "type": "completed",
+                "description": "Research completed",
+            },
+            session_key,
+        )
+    except asyncio.CancelledError:
+        # Send cancellation message before propagating the exception
+        yield make_message(
+            {
+                "type": "cancelled",
+                "description": "Research was cancelled",
+            },
+            session_key,
+        )
+        raise

backend/requirements.txt

@@ -0,0 +1,10 @@
+fastapi
+uvicorn
+python-dotenv
+attr
+datasets
+docstring_parser
+evaluate
+openai==1.65.1
+transformers
+tavily-python

backend/scan_research.py

@@ -0,0 +1,536 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Core research and reporting module for the Universal Deep Research Backend (UDR-B).
+
+This module provides the main research functionality including:
+- Query analysis and topic extraction
+- Web search using Tavily API
+- Content filtering and relevance scoring
+- Report generation using LLMs
+"""
+
+import asyncio
+import random
+from typing import Any, AsyncGenerator, Dict, List
+
+from openai import OpenAI
+from tavily import TavilyClient
+
+import items
+from clients import (
+    create_lm_client,
+    create_tavily_client,
+    get_completion,
+    is_output_positive,
+)
+from config import get_config
+from sessions import generate_session_key
+
+# Get configuration
+config = get_config()
+
+# Use configuration values
+MAX_TOPICS: int = config.research.max_topics
+MAX_SEARCH_PHRASES: int = config.research.max_search_phrases
+
+
+def build_research_artifacts_path(session_key: str) -> str:
+    return f"instances/{session_key}.research_artifacts.jsonl"
+
+
+def build_reporting_artifacts_path(session_key: str) -> str:
+    return f"instances/{session_key}.reporting_artifacts.jsonl"
+
+
+def make_event(
+    type: str,
+    description: str,
+    hidden: bool = False,
+    deltaSearchCount: int = 0,
+    deltaQueryCount: int = 0,
+    report: str | None = None,
+) -> Dict[str, Any]:
+    return {
+        "type": type,
+        "description": description,
+        "hidden": hidden,
+        "deltaSearchCount": deltaSearchCount,
+        "deltaQueryCount": deltaQueryCount,
+        **({"report": report} if report is not None else {}),
+    }
+
+
+async def do_research(
+    session_key: str, prompt: str
+) -> AsyncGenerator[Dict[str, Any], None]:
+    """
+    Performs research based on the provided query and yields events as they occur.
+
+    This function handles the research phase, including:
+    - Receipt and analysis of the research query
+    - Planning the research approach
+    - Searching for relevant information
+    - Filtering and categorizing results
+    - Aggregating findings into a coherent output
+
+    Events yielded:
+    - prompt_received: Initial receipt of the research query
+    - prompt_analysis: Analysis of the query's requirements
+    - research_planning: Planning the research approach
+    - topic_exploration_started: Starting research on each topic
+    - search_started: Initiating a search for each search phrase
+    - search_result_processing_started: Processing the search results
+    - aggregation_started: Beginning the aggregation of relevant segments
+    - research_completed: Completion of the research phase
+
+    Args:
+        session_key (str): A unique identifier for the research session.
+        prompt (str): The research query to process.
+
+    Yields:
+        Dict containing:
+        - type (str): The event type.
+        - description (str): User-friendly description of the event.
+        - hidden (bool, default=False): Whether the event is hidden from the user or should be displayed.
+        - deltaSearchCount (int, optional): The number of search queries performed.
+        - deltaQueryCount (int, optional): The number of queries performed.
+        - report (str, optional): The report produced.
+    """
+
+    research_artifacts_path: str = build_research_artifacts_path(session_key)
+    items.register_item(research_artifacts_path, {"type": "prompt", "prompt": prompt})
+
+    client = create_lm_client()
+    tavily_client = create_tavily_client()
+
+    yield make_event(
+        "prompt_received",
+        f"Received research request: '{prompt}'",
+    )
+
+    prompt_valid: bool = check_if_prompt_is_valid(client, prompt)
+    items.register_item(
+        research_artifacts_path, {"type": "prompt_validity", "valid": prompt_valid}
+    )
+    if not prompt_valid:
+        yield make_event(
+            "error",
+            "It would appear that the prompt is not a valid document research prompt. Please try again with a valid prompt.",
+            deltaQueryCount=1,
+        )
+        return
+
+    yield {
+        "type": "prompt_analysis_started",
+        "description": "Analyzing the research request...",
+        "hidden": False,
+    }
+
+    task_prompt, format_prompt = perform_prompt_decomposition(client, prompt)
+    items.register_item(
+        research_artifacts_path, {"type": "task_prompt", "task_prompt": task_prompt}
+    )
+    items.register_item(
+        research_artifacts_path,
+        {"type": "format_prompt", "format_prompt": format_prompt},
+    )
+
+    yield make_event(
+        "prompt_analysis_completed",
+        f"Prompt analysis completed. Will analyze the following task assignment: '{task_prompt}'.",
+        deltaQueryCount=1,
+    )
+
+    topics: List[str] = generate_topics(client, task_prompt)
+    items.register_item(research_artifacts_path, {"type": "topics", "topics": topics})
+    yield make_event(
+        "task_analysis_completed",
+        f"Task analysis completed. Will be researching {len(topics)}+ topics.",
+        deltaQueryCount=1,
+    )
+
+    topic_relevant_segments: dict[str, List[str]] = {}
+    search_result_urls: List[str] = []
+    all_results: List[Dict[str, Any]] = []
+    for topic in topics:
+        yield make_event(
+            "topic_exploration_started",
+            f"Researching '{topic}'",
+        )
+
+        search_phrases: List[str] = produce_search_phrases(client, prompt, topic)
+        items.register_item(
+            research_artifacts_path,
+            {
+                "type": "topic_search_phrases",
+                "topic": topic,
+                "search_phrases": search_phrases,
+            },
+        )
+
+        yield make_event(
+            "topic_exploration_completed",
+            f"Will invoke {len(search_phrases)} search phrases to research '{topic}'.",
+            deltaQueryCount=1,
+        )
+
+        topic_relevant_segments[topic] = []
+        for search_phrase in search_phrases:
+            yield make_event(
+                "search_started",
+                f"Searching for '{search_phrase}'",
+            )
+
+            search_results: List[Dict[str, Any]] = perform_search(
+                tavily_client, search_phrase, research_artifacts_path
+            )
+            items.register_item(
+                research_artifacts_path,
+                {
+                    "type": "topic_search_results",
+                    "topic": topic,
+                    "search_phrase": search_phrase,
+                    "results": search_results,
+                },
+            )
+            original_search_result_urls: List[str] = [
+                result["url"]
+                for result in search_results
+                if result["url"] not in search_result_urls
+            ]
+            search_result_urls.extend(original_search_result_urls)
+            original_search_results = [
+                result
+                for result in search_results
+                if result["url"] in original_search_result_urls
+            ]
+            all_results.extend(original_search_results)
+
+            yield make_event(
+                "search_result_processing_started",
+                f"Processing {len(original_search_result_urls)} search results.",
+                deltaSearchCount=1,
+            )
+
+            for search_result in original_search_results:
+                search_result_content: str = search_result["raw_content"]
+                search_result_url: str = search_result["url"]
+                search_result_url_index: int = search_result_urls.index(
+                    search_result_url
+                )
+                relevant_segments: List[str] = find_relevant_segments(
+                    client,
+                    prompt,
+                    topic,
+                    search_result_content,
+                    search_result_url_index,
+                )
+                topic_relevant_segments[topic].extend(relevant_segments)
+                items.register_item(
+                    research_artifacts_path,
+                    {
+                        "type": "topic_search_result_relevant_segments",
+                        "topic": topic,
+                        "search_phrase": search_phrase,
+                        "search_result": search_result,
+                        "relevant_segments": relevant_segments,
+                    },
+                )
+
+                yield make_event(
+                    "search_result_processing_completed",
+                    f"Processed search result {search_result_url_index}.",
+                    hidden=True,
+                    deltaQueryCount=1,
+                )
+
+    yield make_event(
+        "aggregation_started",
+        "Aggregating relevant information for all topics.",
+    )
+
+    items.register_item(
+        research_artifacts_path,
+        {
+            "type": "topic_relevant_segments",
+            "topic_relevant_segments": topic_relevant_segments,
+            "search_result_urls": search_result_urls,
+        },
+    )
+    items.register_item(
+        research_artifacts_path, {"type": "all_results", "all_results": all_results}
+    )
+
+    # sleep for 0.5s
+    await asyncio.sleep(0.5)
+
+    yield make_event(
+        "research_completed",
+        "Research phase completed.",
+    )
+
+
+async def do_reporting(session_key: str) -> AsyncGenerator[Dict[str, Any], None]:
+    """
+    Generates a report based on the research findings and yields events as they occur.
+
+    This function handles the reporting phase, including:
+    - Report construction
+    - Formatting and organization
+    - Final delivery
+
+    Events yielded:
+    - report_building: Initial report construction
+    - report_formatting: Formatting and structuring the report
+    - report_done: Report completion and delivery
+
+    Yields:
+        Dict containing:
+        - type (str): The event type
+        - description (str): User-friendly description of the event
+        - hidden (bool, default=False): Whether the event is hidden from the user or should be displayed
+        - deltaSearchCount (int, optional): The number of search queries performed
+        - deltaQueryCount (int, optional): The number of queries performed
+        - report (str, optional): The report produced
+    """
+
+    client = create_lm_client()
+
+    research_artifacts_path: str = build_research_artifacts_path(session_key)
+    task_prompt: str = items.find_item_by_type(research_artifacts_path, "task_prompt")[
+        "task_prompt"
+    ]
+    format_prompt: str = items.find_item_by_type(
+        research_artifacts_path, "format_prompt"
+    )["format_prompt"]
+    topic_relevant_segments: dict[str, List[str]] = items.find_item_by_type(
+        research_artifacts_path, "topic_relevant_segments"
+    )["topic_relevant_segments"]
+    search_result_urls: List[str] = items.find_item_by_type(
+        research_artifacts_path, "topic_relevant_segments"
+    )["search_result_urls"]
+    all_results: List[Dict[str, Any]] = items.find_item_by_type(
+        research_artifacts_path, "all_results"
+    )["all_results"]
+
+    yield make_event(
+        "report_building",
+        "Building the report...",
+    )
+
+    reporting_artifacts_path: str = build_reporting_artifacts_path(session_key)
+    report: str = produce_report(
+        client, task_prompt, format_prompt, topic_relevant_segments
+    )
+    items.register_item(reporting_artifacts_path, {"type": "report", "report": report})
+
+    # Step 3: Ensure that the report is consistent and formatted correctly in Markdown
+    yield make_event(
+        "report_processing",
+        "Formatting the report...",
+        deltaQueryCount=1,
+    )
+    consistent_report: str = ensure_format_is_respected(
+        client, task_prompt, format_prompt, report
+    )
+    consistent_report += "\n\n"
+    consistent_report += "---\n"
+    for search_result_url_index, search_result_url in enumerate(search_result_urls):
+        result = next(
+            (result for result in all_results if result["url"] == search_result_url),
+            None,
+        )
+        consistent_report += f" - [[{search_result_url_index}]] [{result['title']}][{search_result_url_index}]\n"
+    consistent_report += "\n\n"
+    for search_result_url_index, search_result_url in enumerate(search_result_urls):
+        consistent_report += f"[{search_result_url_index}]: {search_result_url}\n"
+    items.register_item(
+        reporting_artifacts_path,
+        {"type": "consistent_report", "consistent_report": consistent_report},
+    )
+
+    yield make_event(
+        "report_done",
+        "Report completed.",
+        report=consistent_report,
+        deltaQueryCount=1,
+    )
+
+
+# ERRANDS
+def check_if_prompt_is_valid(client: OpenAI, prompt: str) -> bool:
+    messages = [
+        {
+            "role": "system",
+            "content": "You are a helpful assistant that checks if a prompt is a valid deep information research prompt. A valid prompt is in English and gives a task to research one or more topics and produce a report. Invalid prompts are general language model prompts that ask simple (perhaps even yes or no) questions, ask forexplanations, or attempt to have a conversation. Examples of valid prompts: 'What was the capital of France in 1338?', 'Write a report on stock market situation on during this morning', 'Produce a thorough report on the major event happened in the Christian world on the 21st of April 2025.', 'Produce a report on the differences between the US and European economy health in 2024.', 'What is the short history of the internet?'. Examples of invalid prompts: 'Is the weather in Tokyo good?', 'ppdafsfgr hdafdf', 'Hello, how are you?', 'The following is a code. Can you please explain it to me and then simulate it?'",
+        },
+        {
+            "role": "user",
+            "content": f"Is the following prompt a valid information research prompt? Respond with 'yes' or 'no'. Do not output any other text.\n\n{prompt}\n\n Reminders: Find out if the above-given prompt is a valid information research prompt. Do not output any other text.",
+        },
+    ]
+    return is_output_positive(get_completion(client, messages))
+
+
+def perform_prompt_decomposition(client: OpenAI, prompt: str) -> List[str]:
+    messages = [
+        {
+            "role": "system",
+            "content": "You are a helpful assistant that decomposes a prompt into a task to be performed and a format in which the report should be produced. The output should be two prompts separated by a double-newline. The first prompt is the task to be performed, and the second prompt is the format in which the report should be produced. If there is no formatting constraint, output 'No formatting constraint' in the second prompt. Do not output any other text.",
+        },
+        {
+            "role": "user",
+            "content": f"Decompose the PROMPT into a task to be performed and a format in which the report should be produced. If there is no formatting constraint, output 'No formatting constraint' in the second prompt. Do not output any other text.\n\nEXAMPLE PROMPT:\nWrite a three-chapter report on the differences between the US and European economy health in 2024. The first chapter should be about the US economy health, the second chapter should be about the European economy health, and the third chapter should be about the differences between the two.\n\nEXAMPLE OUTPUT:\nWrite a report on the differences between the US and European economy health in 2024.\n\nThe report should be in the form of a three-chapter report. The first chapter should be about the US economy health, the second chapter should be about the European economy health, and the third chapter should be about the differences between the two.\n\nPROMPT: {prompt}\n\nReminders: The output should be two prompts separated by a double-newline. The first prompt is the task to be performed, and the second prompt is the format in which the report should be produced. If there is no formatting constraint, output 'No formatting constraint' in the second prompt. Do not output any other text.",
+        },
+    ]
+    decomposition = get_completion(client, messages).split("\n\n")
+    if len(decomposition) != 2:
+        raise ValueError(
+            f"Failed to perform prompt decomposition; decomposition: {decomposition}"
+        )
+    return decomposition
+
+
+def generate_topics(client: OpenAI, prompt: str) -> List[str]:
+    messages = [
+        {
+            "role": "system",
+            "content": f"You are a helpful assistant that decomposes a prompt into a list of topics to research. The output should be a list of strings separated by newlines, each representing a topic to research. The topics should be in English and should be specific and focused. Output at most {MAX_TOPICS} topics. Examples:\n\nPrompt: What was the capital of France in 1338?\nThe capital and seat of government of France in 1338\n\nPrompt: Produce a report on the differences between the US and European economy health in 2024\nUS economy health in 2024\nEuropean economy health in 2024\nGeneral differences between the US and European economy health in 2024\n\nPrompt: What is the short history of the internet?:\nThe history of the internet\n\nPrompt: Report on US crude oil prices in relation to Gold prices in 1970-1980\nUS crude oil prices in 1970-1980\nGold prices in 1970-1980\nGold-crude oil correlation in 1970-1980",
+        },
+        {
+            "role": "user",
+            "content": f"Decompose the following prompt into a list of topics to research:\n\nPrompt: {prompt}\n\nReminders: The output should be a list of strings separated by newlines, each representing a topic to research. The topics should be in English and should be specific and focused. Do not output any other text. Output at most {MAX_TOPICS} topics.",
+        },
+    ]
+    completion: str = get_completion(client, messages)
+    completion_lines: List[str] = completion.split("\n")
+    ret = [line.strip() for line in completion_lines if line.strip()]
+    if len(ret) > MAX_TOPICS:
+        ret = random.sample(ret, MAX_TOPICS)
+    return ret
+
+
+def produce_search_phrases(client: OpenAI, prompt: str, topic: str) -> List[str]:
+    messages = [
+        {
+            "role": "system",
+            "content": f"You are a helpful assistant that produces a list of search phrases for a given topic. The output should be a newline-separated list of short search phrases that can be used in e.g. Google or Bing search engines. Output at most {MAX_SEARCH_PHRASES} search phrases. Examples:\n\nTopic: The capital and seat of government of France in 1338\nSearch phrases: The capital of France in 1338, The seat of government of France in 1338, Government of France in 1338 century, Government of France in the 14th century\n\nTopic: US crude oil prices in relation to Gold prices in 1970-1980\nSearch phrases: US crude oil prices in 1970-1980, Gold prices in 1970-1980, Gold-crude oil correlation in 1970-1980, Gold-crude oil correlation\n\nTopic: {topic}\nSearch phrases:",
+        },
+        {
+            "role": "user",
+            "content": f"Produce a list of search phrases for the following topic:\n\nPrompt (added for context): {prompt}\n\nTopic: {topic}\n\nReminders: The output should be a list of search phrases for the given topic separated by newlines. The search phrases should be in English and should be specific and focused. Output at most {MAX_SEARCH_PHRASES} search phrases. Do not output any other text.",
+        },
+    ]
+    completion: str = get_completion(client, messages)
+    completion_lines: List[str] = completion.split("\n")
+    ret = [line.strip() for line in completion_lines if line.strip()]
+    if len(ret) > MAX_SEARCH_PHRASES:
+        ret = random.sample(ret, MAX_SEARCH_PHRASES)
+    return ret
+
+
+def perform_search(
+    client: TavilyClient, search_phrase: str, research_artifacts_path: str
+) -> List[Dict[str, Any]]:
+    search_response: Dict[str, Any] = client.search(
+        search_phrase, include_raw_content=True
+    )
+    items.register_item(
+        research_artifacts_path,
+        {
+            "type": "search_response_raw",
+            "search_phrase": search_phrase,
+            "response": search_response,
+        },
+    )
+    filtered_results: List[Dict[str, Any]] = [
+        result
+        for result in search_response["results"]
+        if result["raw_content"] is not None and result["raw_content"].strip() != ""
+    ]
+    items.register_item(
+        research_artifacts_path,
+        {
+            "type": "search_response_filtered",
+            "search_phrase": search_phrase,
+            "response": filtered_results,
+        },
+    )
+    return filtered_results
+
+
+def find_relevant_segments(
+    client: OpenAI,
+    prompt: str,
+    topic: str,
+    search_result: str,
+    search_result_url_index: int,
+) -> List[str]:
+    messages = [
+        {
+            "role": "system",
+            "content": "You are a helpful assistant that finds relevant paragraphs in a given search result. The output should be a double-newline-separated list of relevant paragraphs. A paragraph can be a couple of sentences to dozens of sentences if they are really relevant. If there are no relevant paragraphs, just output an empty line or two and stop the generation. Do not output any other text.",
+        },
+        {
+            "role": "user",
+            "content": f"Find the sentences or paragraphs relevant to the following prompt in the following search result:\n\nSearch result: {search_result}\n\nPrompt (added for context): {prompt}\n\nTopic: {topic}\n\nReminders: The output should be a list of relevant paragraphs for the given topic separated by double-newlines. The relevant paragraphs should be in English and should be genuinely relevant to the prompt. Do not output any other text.",
+        },
+    ]
+    ret = get_completion(client, messages).split("\n")
+    ret = [line.strip() for line in ret if line.strip()]
+    ret = [f"[[{search_result_url_index}]] {paragraph}" for paragraph in ret]
+    return ret
+
+
+def produce_report(
+    client: OpenAI,
+    prompt: str,
+    format_prompt: str,
+    topic_relevant_segments: dict[str, List[str]],
+) -> str:
+    topic_relevant_segments_str: str = "\n".join(
+        [
+            f"Topic: {topic}\n{'\n'.join(segments)}"
+            for topic, segments in topic_relevant_segments.items()
+        ]
+    )
+    messages = [
+        {
+            "role": "system",
+            "content": "You are a helpful assistant that produces a report based on the aggregated per-topic relevant paragraphs while citing sources. The output should be a report in Markdown format. The report should be self-consistent and formatted correctly in Markdown. Do not output any other text.",
+        },
+        {
+            "role": "user",
+            "content": f"Produce a report based on the following aggregated per-topic relevant paragraphs. Each paragraph contains an index of a source. Make sure to refer to this index in the form [[index]] every time you rely on the information from the source. Respect the format prompt. Do not output any other text.\n\nReport prompt: {prompt}\n\nTopic relevant paragraphs: {topic_relevant_segments_str}\n\nFormat prompt: {format_prompt}\n\nReminders: The output should be a report in Markdown format. The report should be formatted correctly according to the Format prompt in Markdown. Every single mention of an information stemming from one of the sources should be accompanied by the source index in the form [[index]] (or [[index1,index2,...]]) within or after the statement of the information. A list of the source URLs to correspond to the indices will be provided separately -- do not attempt to output it. Do not output any other text.",
+        },
+    ]
+    return get_completion(client, messages).strip()
+
+
+def ensure_format_is_respected(
+    client: OpenAI, prompt: str, format_prompt: str, report: str
+) -> str:
+    messages = [
+        {
+            "role": "system",
+            "content": "You are a helpful assistant that ensures that a report is properly formatted. The output should be a report in Markdown format and follow the format prompt. The report should be formatted correctly in Markdown. Note that double horizontal rule (.e.g ==== etc.) are not supported in official Markdown. Do not output any other text.",
+        },
+        {
+            "role": "user",
+            "content": f"Ensure that the following report is properly formatted according to the format prompt. Do not output the Markdown output as code (i.e. enclosed in ```) -- just output the Markdown. Do not remove any references in the form [[index]] -- keep them in the text! The list of sources will be provided separately.\n\nReport: {report}\n\nFormat prompt: {format_prompt}\n\nReminders: The output should be a report in Markdown format. The report should be self-consistent and formatted correctly in Markdown. Do not output the Markdown output as code (i.e. enclosed in ```) -- just output the Markdown. Do not remove any references in the form [[index]] -- keep them in the text! The list of sources will be provided separately. Do not output any other text.",
+        },
+    ]
+    return get_completion(client, messages).strip()

backend/scan_research_dry.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import asyncio
+import json
+import random
+from datetime import datetime
+from glob import glob
+from typing import Any, AsyncGenerator, Dict, List
+
+
+async def do_research(
+    session_key: str,
+    query: str,
+    mock_directory: str = "mock_instances/stocks_24th_3_sections",
+) -> AsyncGenerator[Dict[str, Any], None]:
+    """
+    Generator that reads and replays events from mock_instances with random delays.
+    Does not save any artifacts or events.
+
+    Args:
+        query: The research query to process (ignored in dry mode)
+        session_key: Unique identifier for this research session (ignored in dry mode)
+        mock_directory: Directory containing mock instance files to replay
+
+    Yields:
+        Dict containing event data from the mock instance
+    """
+    # Find the mock instance files
+    mock_files = glob(f"{mock_directory}/*.events.jsonl")
+    if not mock_files:
+        yield {
+            "type": "error",
+            "description": "No mock instance files found in mock_instances directory",
+        }
+        return
+
+    # Use the first mock file found
+    mock_file = mock_files[0]
+
+    # Read all events from the mock file
+    with open(mock_file, "r") as f:
+        events = [json.loads(line) for line in f if line.strip()]
+
+    # Filter for non-reporting events
+    research_events = [
+        event
+        for event in events
+        if not event.get("type", "").startswith("report_")
+        and event.get("type", "") != "completed"
+    ]
+
+    # Replay each event with a random delay
+    for event in research_events:
+        # Update timestamp to current time
+        event["timestamp"] = datetime.now().isoformat()
+        # Yield the event
+        yield event
+        # Wait for a random time between 0.5 and 2 seconds
+        await asyncio.sleep(random.uniform(0.5, 2.0))
+
+
+async def do_reporting(
+    session_key: str, mock_directory: str = "mock_instances/stocks_24th_3_sections"
+) -> AsyncGenerator[Dict[str, Any], None]:
+    """
+    Generator that reads and replays reporting events from mock_instances with random delays.
+    Does not save any artifacts or events.
+
+    Args:
+        session_key: Unique identifier for this research session (ignored in dry mode)
+        mock_directory: Directory containing mock instance files to replay
+
+    Yields:
+        Dict containing event data from the mock instance
+    """
+    # Find the mock instance files
+    mock_files = glob(f"{mock_directory}/*.events.jsonl")
+    if not mock_files:
+        yield {
+            "type": "error",
+            "description": "No mock instance files found in mock_instances directory",
+        }
+        return
+
+    # Use the first mock file found
+    mock_file = mock_files[0]
+
+    # Read all events from the mock file
+    with open(mock_file, "r") as f:
+        events = [json.loads(line) for line in f if line.strip()]
+
+    # Filter for reporting events
+    reporting_events = [
+        event for event in events if event.get("type", "").startswith("report_")
+    ]
+
+    # Replay each event with a random delay
+    for event in reporting_events:
+        # Update timestamp to current time
+        event["timestamp"] = datetime.now().isoformat()
+        # Yield the event
+        yield event
+        # Wait for a random time between 0.5 and 2 seconds
+        await asyncio.sleep(random.uniform(0.5, 2.0))

backend/sessions.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Session management utilities for the Universal Deep Research Backend (UDR-B).
+
+This module provides functions for generating unique session identifiers
+that combine timestamps with random components for tracking research sessions.
+"""
+
+import uuid
+from datetime import datetime
+
+
+def generate_session_key() -> str:
+    """
+    Generates a unique session key combining timestamp and random components.
+    Format: {timestamp}-{random_uuid}
+    Example: "20240315T123456Z-a1b2c3d4"
+
+    Returns:
+        str: A unique session identifier
+    """
+    timestamp = datetime.now().strftime("%Y%m%dT%H%M%SZ")
+    random_component = str(uuid.uuid4())[:8]  # First 8 chars of UUID
+    return f"{timestamp}-{random_component}"

backend/setup.py

@@ -0,0 +1,204 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#!/usr/bin/env python3
+"""
+Setup script for the Universal Deep Research Backend (UDR-B).
+
+This script helps users configure the backend by:
+1. Creating necessary directories
+2. Setting up environment configuration
+3. Validating API key files
+4. Installing dependencies
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def print_header(title: str):
+    """Print a formatted header."""
+    print(f"\n{'='*60}")
+    print(f" {title}")
+    print(f"{'='*60}")
+
+
+def print_step(step: str):
+    """Print a step message."""
+    print(f"\n→ {step}")
+
+
+def check_python_version():
+    """Check if Python version is compatible."""
+    print_step("Checking Python version...")
+    if sys.version_info < (3, 8):
+        print("❌ Python 3.8 or higher is required")
+        sys.exit(1)
+    print(f"✅ Python {sys.version_info.major}.{sys.version_info.minor} detected")
+
+
+def create_directories():
+    """Create necessary directories."""
+    print_step("Creating directories...")
+    directories = ["logs", "instances", "mock_instances"]
+
+    for directory in directories:
+        Path(directory).mkdir(exist_ok=True)
+        print(f"✅ Created directory: {directory}")
+
+
+def setup_env_file():
+    """Set up environment configuration file."""
+    print_step("Setting up environment configuration...")
+
+    env_file = Path(".env")
+    env_example = Path("env.example")
+
+    if env_file.exists():
+        print("✅ .env file already exists")
+        return
+
+    if env_example.exists():
+        # Copy example file
+        with open(env_example, "r") as f:
+            content = f.read()
+
+        with open(env_file, "w") as f:
+            f.write(content)
+
+        print("✅ Created .env file from env.example")
+        print("⚠️  Please edit .env file with your configuration")
+    else:
+        print("❌ env.example file not found")
+        print("Creating basic .env file...")
+
+        basic_env = """# Universal Deep Research Backend (UDR-B) - Environment Configuration
+HOST=0.0.0.0
+PORT=8000
+LOG_LEVEL=info
+FRONTEND_URL=http://localhost:3000
+DEFAULT_MODEL=llama-3.1-nemotron-253b
+LLM_API_KEY_FILE=nvdev_api.txt
+TAVILY_API_KEY_FILE=tavily_api.txt
+MAX_TOPICS=1
+MAX_SEARCH_PHRASES=1
+LOG_DIR=logs
+"""
+        with open(env_file, "w") as f:
+            f.write(basic_env)
+
+        print("✅ Created basic .env file")
+        print("⚠️  Please edit .env file with your configuration")
+
+
+def check_api_keys():
+    """Check for required API key files."""
+    print_step("Checking API key files...")
+
+    required_files = ["nvdev_api.txt", "tavily_api.txt"]
+
+    missing_files = []
+    for file in required_files:
+        if Path(file).exists():
+            print(f"✅ {file} found")
+        else:
+            print(f"❌ {file} missing")
+            missing_files.append(file)
+
+    if missing_files:
+        print(f"\n⚠️  Missing API key files: {', '.join(missing_files)}")
+        print("Please create these files with your API keys:")
+        for file in missing_files:
+            print(f"  - {file}")
+        print("\nExample:")
+        print("  echo 'your-api-key-here' > nvdev_api.txt")
+        print("  echo 'your-tavily-key-here' > tavily_api.txt")
+
+
+def install_dependencies():
+    """Install Python dependencies."""
+    print_step("Installing dependencies...")
+
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", "-r", "requirements.txt"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        print("✅ Dependencies installed successfully")
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Failed to install dependencies: {e}")
+        print("Please run: pip install -r requirements.txt")
+
+
+def validate_setup():
+    """Validate the setup."""
+    print_step("Validating setup...")
+
+    # Check if main modules can be imported
+    try:
+        import clients
+        import config
+        import main
+        import scan_research
+
+        print("✅ All modules can be imported")
+    except ImportError as e:
+        print(f"❌ Import error: {e}")
+        return False
+
+    # Check if directories exist
+    required_dirs = ["logs", "instances"]
+    for directory in required_dirs:
+        if not Path(directory).exists():
+            print(f"❌ Directory missing: {directory}")
+            return False
+
+    print("✅ Setup validation passed")
+    return True
+
+
+def main():
+    """Main setup function."""
+    print_header("Universal Deep Research Backend (UDR-B) Setup")
+
+    # Change to script directory
+    script_dir = Path(__file__).parent
+    os.chdir(script_dir)
+
+    check_python_version()
+    create_directories()
+    setup_env_file()
+    check_api_keys()
+    install_dependencies()
+
+    if validate_setup():
+        print_header("Setup Complete!")
+        print("🎉 Your Universal Deep Research Backend (UDR-B) is ready!")
+        print("\nNext steps:")
+        print("1. Edit .env file with your configuration")
+        print("2. Create API key files (nvdev_api.txt, tavily_api.txt)")
+        print("3. Run: ./launch_server.sh")
+        print("4. Or run: uvicorn main:app --reload")
+        print("\nFor more information, see README.md")
+    else:
+        print_header("Setup Failed")
+        print("❌ Please fix the issues above and run setup again")
+
+
+if __name__ == "__main__":
+    main()

frontend/.gitignore

@@ -0,0 +1,48 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# development logs
+npm_run_dev.txt
+uvicorn_main.txt
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+
+**/.DS_Store

frontend/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to Universal Deep Research Frontend
+
+This code details a research and demonstration prototype. This software is not intended for production use.
+
+## How to Contribute
+
+### 1. Fork and Clone
+
+```bash
+git clone <your-fork-url>
+cd frontend
+```
+
+### 2. Set Up Development Environment
+
+```bash
+npm install
+# or
+yarn install
+```
+
+### 3. Make Changes
+
+- Follow existing code style and patterns
+- Add tests for new functionality
+- Update documentation as needed
+- Ensure all TODO comments are addressed or documented
+
+### 4. Testing
+
+- Test components manually in development mode
+- Verify UI changes work correctly across different screen sizes
+- Ensure accessibility standards are maintained
+
+### 5. Submit Pull Request
+
+- Create a descriptive PR title
+- Include clear description of changes
+- Ensure code follows research/demonstration focus
+
+## Code Standards
+
+- **TypeScript**: Follow TypeScript best practices and strict mode
+- **React**: Use functional components with hooks
+- **Next.js**: Follow Next.js 13+ App Router conventions
+- **CSS**: Use CSS modules for component styling
+- **Documentation**: Use clear JSDoc comments and inline documentation
+- **Error Handling**: Implement proper error boundaries and error states
+- **Configuration**: Use environment variables for customization
+- **Accessibility**: Follow WCAG guidelines and use semantic HTML
+
+## Development Commands
+
+```bash
+# Start development server
+npm run dev
+# or
+yarn dev
+
+# Build for production
+npm run build
+# or
+yarn build
+
+# Run linting
+npm run lint
+# or
+yarn lint
+
+# Run type checking
+npm run type-check
+# or
+yarn type-check
+```
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same terms as this project (research/demonstration use only). You can find the license in [LICENSE](../LICENSE.txt).
+
+#### Signing Your Work
+
+- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
+
+  - Any contribution which contains commits that are not Signed-Off will not be accepted.
+
+- To sign off on a commit you simply use the `--signoff` (or `-s`) option when committing your changes:
+
+  ```bash
+  $ git commit -s -m "Add cool feature."
+  ```
+
+  This will append the following to your commit message:
+
+  ```
+  Signed-off-by: Your Name <[email protected]>
+  ```
+
+- Full text of the DCO:
+
+  ```
+    Developer Certificate of Origin
+    Version 1.1
+
+    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+    1 Letterman Drive
+    Suite D4700
+    San Francisco, CA, 94129
+
+    Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+  ```
+
+  ```
+    Developer's Certificate of Origin 1.1
+
+    By making a contribution to this project, I certify that:
+
+    (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
+
+    (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
+
+    (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
+
+    (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
+  ```

frontend/DISCLAIMER.txt

@@ -0,0 +1,35 @@
+DISCLAIMER
+
+IMPORTANT NOTICE - RESEARCH DEMONSTRATION PROTOTYPE
+
+This software and all associated code, documentation, and materials (collectively, the "Software") are provided solely for research and demonstration purposes. The Software is intended exclusively as a prototype to demonstrate research concepts and methodologies in the field of artificial intelligence and automated research systems.
+
+CRITICAL LIMITATIONS AND WARNINGS:
+
+1. RESEARCH PURPOSE ONLY: The Software is designed and intended solely for academic research, educational demonstration, and experimental purposes. It is NOT intended for production use, commercial deployment, or any real-world application.
+
+2. NO PRODUCTION USE: Under no circumstances should this Software be deployed, used, or relied upon in any production environment, commercial application, or any context where reliability, accuracy, or safety is required.
+
+3. EXPERIMENTAL NATURE: The Software contains experimental features, unproven methodologies, and research-grade implementations that may contain bugs, security vulnerabilities, or other issues that could cause data loss, system instability, or other problems.
+
+4. NO WARRANTIES: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR ACCURACY.
+
+5. NO LIABILITY: TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, NEITHER NVIDIA CORPORATION, NOR THE AUTHORS, CONTRIBUTORS, OR ANY OTHER PARTIES INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THE SOFTWARE SHALL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. NO SUPPORT: No technical support, maintenance, updates, or assistance is provided for this Software. Users are solely responsible for their use of the Software and any consequences thereof.
+
+7. NO ENDORSEMENT: The inclusion of any third-party components, APIs, or services does not constitute an endorsement of those services or their providers.
+
+8. COMPLIANCE: Users are responsible for ensuring their use of the Software complies with all applicable laws, regulations, and terms of service for any third-party services or APIs used by the Software.
+
+9. SECURITY: The Software has not been subjected to security audits or testing suitable for production environments. Users assume all risks associated with security vulnerabilities.
+
+10. DATA PRIVACY: The Software may process, transmit, or store data in ways that do not comply with data protection regulations. Users are responsible for ensuring compliance with applicable privacy laws.
+
+ACKNOWLEDGMENT:
+
+By using, copying, modifying, or distributing the Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this disclaimer. If you do not agree to these terms, you must not use the Software.
+
+For questions regarding this disclaimer, please contact the authors through the appropriate channels established for this research project.
+
+Last updated: 07/15/2025.

frontend/README.md

@@ -0,0 +1,171 @@
+# NVR Universal Deep Research - Frontend
+
+A Next.js frontend application for the NVR Universal Deep Research system that provides an interactive interface for intelligent research and reporting capabilities.
+
+This software is provided exclusively for research and demonstration purposes. It is intended solely as a prototype to demonstrate research concepts and methodologies in artificial intelligence and automated research systems.
+
+- This software is not intended for production deployment, commercial use, or any real-world application where reliability, accuracy, or safety is required.
+- This software contains experimental features, unproven methodologies, and research-grade implementations that may contain bugs, security vulnerabilities, or other issues.
+- The software is provided "AS IS" without any warranties. Neither NVIDIA Corporation nor the authors shall be liable for any damages arising from the use of this software to the fullest extent permitted by law.
+
+By using this software, you acknowledge that you have read and understood the complete DISCLAIMER file and agree to be bound by its terms. For the complete legal disclaimer, please see the [DISCLAIMER](DISCLAIMER.txt) file in this directory.
+
+## Features
+
+- Interactive research interface with real-time progress tracking
+- Configurable research strategies
+- Support for both V1 and V2 API endpoints
+- Dry run mode for testing
+- Real-time report generation and viewing
+
+## Configuration
+
+The frontend application is highly configurable through environment variables. Copy the example environment file and customize it for your deployment:
+
+```bash
+cp env.example .env.local
+```
+
+### Environment Variables
+
+#### Backend API Configuration
+
+- `NEXT_PUBLIC_BACKEND_BASE_URL`: The base URL of your backend server (default: `http://localhost`)
+- `NEXT_PUBLIC_BACKEND_PORT`: The port your backend server is running on (default: `8000`)
+- `NEXT_PUBLIC_API_VERSION`: API version to use - `v1` or `v2` (default: `v2`)
+
+#### Runtime Configuration
+
+- `NEXT_PUBLIC_DRY_RUN`: Enable dry run mode - `true` or `false` (default: `false`)
+- `NEXT_PUBLIC_ENABLE_V2_API`: Enable V2 API - `true` or `false` (default: `true`)
+
+#### Frontend Configuration
+
+- `NEXT_PUBLIC_FRONTEND_PORT`: The port for the frontend development server (default: `3000`)
+- `NEXT_PUBLIC_FRONTEND_HOST`: The host for the frontend development server (default: `localhost`)
+
+### Example Configuration
+
+For a production deployment with a backend on a different server:
+
+```bash
+NEXT_PUBLIC_BACKEND_BASE_URL=http://your-backend-server.com
+NEXT_PUBLIC_BACKEND_PORT=8000
+NEXT_PUBLIC_API_VERSION=v2
+NEXT_PUBLIC_DRY_RUN=false
+NEXT_PUBLIC_ENABLE_V2_API=true
+```
+
+For local development:
+
+```bash
+NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost
+NEXT_PUBLIC_BACKEND_PORT=8000
+NEXT_PUBLIC_API_VERSION=v2
+NEXT_PUBLIC_DRY_RUN=true
+NEXT_PUBLIC_ENABLE_V2_API=true
+```
+
+## Getting Started
+
+1. **Install dependencies:**
+
+   ```bash
+   npm install
+   ```
+
+2. **Configure environment variables:**
+
+   ```bash
+   cp env.example .env.local
+   # Edit .env.local with your configuration
+   ```
+
+3. **Run the development server:**
+
+   ```bash
+   npm run dev
+   ```
+
+4. **Open your browser:**
+   Navigate to [http://localhost:3000](http://localhost:3000) to see the application.
+
+## Available Scripts
+
+- `npm run dev` - Start the development server with Turbopack
+- `npm run build` - Build the application for production
+- `npm run start` - Start the production server
+- `npm run lint` - Run ESLint
+
+## Project Structure
+
+```
+src/
+├── app/                 # Next.js app directory
+│   ├── page.tsx        # Main application page
+│   ├── layout.tsx      # Root layout
+│   └── globals.css     # Global styles
+├── components/         # React components
+│   ├── PromptBar.tsx   # Main input interface
+│   ├── ResearchProgressList.tsx  # Progress tracking
+│   ├── ReportViewer.tsx # Report display
+│   └── ...            # Other UI components
+├── config/            # Configuration management
+│   └── index.ts       # App configuration
+└── types/             # TypeScript type definitions
+    └── ApplicationState.ts
+```
+
+## Backend Requirements
+
+This frontend requires a compatible backend server running the NVR Universal Deep Research API. The backend should:
+
+- Support both `/api/research` (V1) and `/api/research2` (V2) endpoints
+- Accept POST requests with JSON payloads
+- Return Server-Sent Events (SSE) for real-time progress updates
+- Support the dry run mode parameter
+
+## Deployment
+
+The application can be deployed to any platform that supports Next.js:
+
+1. Build the application: `npm run build`
+2. Start the production server: `npm run start`
+3. Set the appropriate environment variables for your deployment
+
+### Example Deployment Platforms
+
+- **Vercel**: Connect your Git repository and set environment variables in the dashboard
+- **Netlify**: Build and deploy with environment variable configuration
+- **Railway**: Deploy with automatic environment variable management
+- **Self-hosted**: Run on your own server with proper environment configuration
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Backend Connection Errors**: Ensure your backend server is running and the `NEXT_PUBLIC_BACKEND_BASE_URL` and `NEXT_PUBLIC_BACKEND_PORT` are correctly configured.
+
+2. **CORS Errors**: Make sure your backend server allows requests from your frontend domain.
+
+3. **API Version Issues**: If you're experiencing API compatibility issues, try switching between `v1` and `v2` using the `NEXT_PUBLIC_API_VERSION` environment variable.
+
+### Development Tips
+
+- Use `NEXT_PUBLIC_DRY_RUN=true` during development to avoid making actual API calls
+- The application supports hot reloading - changes to your code will be reflected immediately
+- Check the browser console for detailed error messages
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test thoroughly
+5. Submit a pull request
+
+## License and Disclaimer
+
+This software is provided for research and demonstration purposes only. Please refer to the [DISCLAIMER](DISCLAIMER.txt) file for complete terms and conditions regarding the use of this software. You can find the license in [LICENSE](LICENSE.txt).
+
+**Do not use this code in production.**

frontend/env.example

@@ -0,0 +1,19 @@
+# Backend API Configuration
+# The base URL of your backend server (without protocol)
+NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost
+# The port your backend server is running on
+NEXT_PUBLIC_BACKEND_PORT=8000
+# API version to use (v1 or v2)
+NEXT_PUBLIC_API_VERSION=v2
+
+# Runtime Configuration
+# Enable dry run mode (true/false)
+NEXT_PUBLIC_DRY_RUN=false
+# Enable V2 API (true/false)
+NEXT_PUBLIC_ENABLE_V2_API=true
+
+# Frontend Configuration
+# The port for the frontend development server
+NEXT_PUBLIC_FRONTEND_PORT=3000
+# The host for the frontend development server
+NEXT_PUBLIC_FRONTEND_HOST=localhost 

frontend/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals", "next/typescript"),
+];
+
+export default eslintConfig;

frontend/launch_server.sh

@@ -0,0 +1 @@
+npm run dev > npm_run_dev.txt 2>&1 & disown $!

frontend/next.config.ts

@@ -0,0 +1,23 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;