BrainCloud 🧠☁️

BrainCloud is a powerful "bring-your-own-keys" deep research web application that leverages AI to conduct comprehensive research on any topic. Built with a modern tech stack featuring Svelte 5 frontend and FastAPI backend, it provides an agent-based approach where AI can utilize multiple tools to gather, analyze, and synthesize information.

✨ Features

• 🤖 Agent-Based Research: Intelligent AI agent that breaks down complex queries into manageable steps
• 🔧 Multi-Tool Integration:
  • Web search via Serper API
  • Document parsing via JINA API
  • AI analysis via OpenAI-compatible APIs
• 🔄 Real-Time Streaming: Live updates as the AI thinks and executes tools
• 📝 Markdown Export: Export research results in well-formatted Markdown
• 🌙 Dark Theme UI: Modern, responsive interface optimized for research workflows
• 🔒 Secure by Design: Client-side credential management with comprehensive data sanitization
• 🚀 High Performance: Async architecture for handling long-running research tasks
• 👥 Multi-Session Support: Handle multiple concurrent users with isolated sessions
• ⏱️ Ephemeral Sessions: Zero persistent storage with 1-hour export windows
• 🛡️ Enhanced Security: Rate limiting, input sanitization, and cryptographic session keys

📖 Usage Guide

Basic Research Flow

1. Configure API Keys: Click the settings icon to open the credentials modal
2. Enter Your Query: Type your research question in the input field
3. Receive Ephemeral Key: Upon starting research, you'll receive a unique ephemeral key
4. Watch the AI Work: See real-time updates as the AI:
   • Thinks through the problem
   • Executes various tools
   • Synthesizes findings
5. Export Results: Download your research as a Markdown file within 1 hour of completion

Advanced Features

Multi-Session Architecture

BrainCloud now supports multiple concurrent users with complete session isolation:

• Each research session receives a unique ephemeral key
• Sessions are completely isolated from each other
• No data persistence between sessions
• Automatic cleanup of expired sessions

Security Features

• Rate Limiting: Prevents abuse with configurable request limits
• Input Sanitization: All user inputs are sanitized to prevent XSS and injection attacks
• Ephemeral Keys: Cryptographically secure 256-bit tokens for session access
• Export Window: 1-hour time limit for exports after research completion
• CORS Protection: Strict origin validation
• Security Headers: Comprehensive security headers on all responses

Credential Modes

BrainCloud supports two credential management modes:

1. User-Supplied Credentials (Default): Users provide their own API keys through the web interface. Keys are encrypted and stored in the browser's localStorage.

2. Server-Supplied Credentials: API keys are configured on the server and never exposed to the frontend. This mode is ideal for:

   • Enterprise deployments
   • Shared team instances
   • Simplified user experience

Configuring Server Credentials:

To enable server-supplied credentials, set the following environment variables:

# Enable server credential mode
USE_SERVER_CREDENTIALS=true

# API Keys (required when server mode is enabled)
OPENAI_API_KEY=your-openai-api-key
JINA_API_KEY=your-jina-api-key
SERPER_API_KEY=your-serper-api-key

# Optional: Custom OpenAI base URL
OPENAI_BASE_URL=https://api.openai.com/v1

When server credential mode is enabled:

• The API Keys button is hidden from the interface
• All API calls use the server-configured credentials
• Users cannot view or modify the API keys
• No credentials are transmitted to or stored in the browser

Security Notes:

• Server credentials should be stored securely using environment variables
• Never commit API keys to version control
• Use appropriate file permissions for .env files (e.g., 600)
• Consider using a secrets management system for production deployments

Custom OpenAI Base URL

You can use OpenAI-compatible APIs by configuring a custom base URL in the credentials modal (user mode) or via the OPENAI_BASE_URL environment variable (server mode).

Research Export Format

Exported Markdown includes:

• Executive summary
• Step-by-step thinking process
• Tool execution details
• Comprehensive findings
• Metadata and citations

🚀 Async Migration (Phase 3 Complete)

BrainCloud has been fully migrated to an asynchronous architecture, providing significant performance improvements:

Key Improvements

• Concurrent Tool Execution: Multiple search queries and webpage visits can now run in parallel
• Real-Time Streaming: Enhanced streaming with better responsiveness and lower latency
• Improved Scalability: Better handling of concurrent users with reduced resource usage
• Non-Blocking Operations: All I/O operations are now fully asynchronous

Performance Gains

Based on our benchmarks:

• Search Operations: Up to 5x faster when processing multiple queries
• Webpage Visits: Up to 3x faster for concurrent URL processing
• Overall Research Time: 40-60% reduction for complex multi-step research tasks

Technical Details

The async migration includes:

• Async versions of all research tools (search, visit, scholar)
• Async DeepResearch agent with streaming support
• Async file operations and utilities
• Comprehensive async test suite with performance benchmarks

For developers, see ASYNC_GUIDE.md for detailed async development guidelines.

🧪 Testing

BrainCloud includes a comprehensive test suite covering all aspects of the multi-session implementation and async functionality:

Running Tests

# Run all tests
pytest

# Run specific test categories
pytest tests/test_ephemeral_sessions.py  # Session lifecycle tests
pytest tests/test_security.py            # Security feature tests
pytest tests/test_multi_session.py       # Multi-session scenarios
pytest tests/test_frontend_integration.py # Frontend integration tests
pytest tests/test_e2e.py                 # End-to-end tests

# Run async-specific tests
pytest tests/test_async_tools.py         # Async tool tests
pytest tests/test_async_agent.py         # Async agent tests
pytest tests/test_async_adapter.py       # Async adapter tests
pytest tests/test_performance_async.py   # Performance benchmarks
pytest tests/test_e2e_async.py          # Async end-to-end tests

# Run with coverage
pytest --cov=src --cov-report=html

# Run performance tests
pytest tests/test_multi_session.py::TestPerformanceAndLoad -v
pytest tests/test_performance_async.py -v  # Async performance benchmarks

Test Categories

1. Session Lifecycle Tests (test_ephemeral_sessions.py)

   • Session creation and expiration
   • Ephemeral key generation and validation
   • Export window enforcement
   • Session cleanup mechanisms

2. Security Tests (test_security.py)

   • Rate limiting functionality
   • Input sanitization
   • API security headers
   • Protection against common attacks

3. Multi-Session Tests (test_multi_session.py)

   • Concurrent user handling
   • Session isolation
   • Performance under load
   • Memory leak prevention

4. Frontend Integration Tests (test_frontend_integration.py)

   • Ephemeral key handling
   • Export functionality
   • Error handling
   • Security feature integration

5. End-to-End Tests (test_e2e.py)

   • Complete user flows
   • Error recovery
   • Security scenarios
   • Performance validation

6. Async Tool Tests (test_async_tools.py)

   • Concurrent search operations
   • Parallel webpage visits
   • Scholar search functionality
   • Error handling and retries

7. Async Agent Tests (test_async_agent.py)

   • Streaming response handling
   • Tool execution coordination
   • Multi-turn conversations
   • Token limit management

8. Async Adapter Tests (test_async_adapter.py)

   • Request/response streaming
   • Session management
   • Credential validation
   • Error propagation

9. Async Performance Tests (test_performance_async.py)

   • Concurrency benchmarks
   • Scalability testing
   • Streaming latency measurements
   • Resource utilization

10. Async End-to-End Tests (test_e2e_async.py)

    • Complete async research flows
    • Concurrent session handling
    • Real-time streaming validation
    • Error recovery scenarios

🚀 Deployment

For detailed deployment and setup instructions, see DEPLOYMENT.md

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Copyright © 2025 Jeff Moe