How stanford-mast/blast works
Project type and purpose
• From the README and file structure, this is a full-stack project whose core is a Python-based “BLAST” engine that exposes an OpenAI-compatible API for web-browsing AI.
• It includes:
• A Python package (blastai/) with modules for serving, execution, caching, scheduling, and resource management.
• A React/Next.js “blastai/frontend” application that provides a browser-based UI for interactive use.
• A separate “website” Next.js project for marketing/documentation.
• Examples, Docs, and CI configuration to support development and deployment.
File structure
Top-level directories:
• .github—CI/CD workflows (e.g. nextjs.yml).
• blastai—core Python package.
– cli.py, server.py, engine.py, executor.py, planner.py, scheduler.py, resource_manager.py, cache.py, config.py, secrets.py, logging_setup.py, response.py, tools.py, utils.py.
– blastai/frontend—a Next.js UI bundled into the Python package for optional local UI serving.
• docs—documentation source (MDX + assets).
• examples—sample Python scripts demonstrating usage of the blastai API.
• website—a standalone Next.js site (marketing, docs link, blog, etc.).
• pyproject.toml—package metadata and dependencies.
README for additional insights
• BLAST is described as a “high-performance serving engine for web browsing AI,” drop-in replacement for OpenAI’s API, with caching, parallelism, streaming, and concurrency.
• Quick-start shows Python client (OpenAI SDK) pointing at http://127.0.0.1:8000 to consume the API.
Main components and their interactions
a. Clients:
• CLI (blastai serve)
• Python/OpenAI SDK clients
• React/Next.js frontend
b. API Server (blastai/server.py)
• Exposes HTTP endpoints (“/v1/responses”, etc.)
• Handles authentication/secrets, config loading.
c. Engine (blastai/engine.py)
• Core orchestration for requests, applies caching logic.
d. Planner (blastai/planner.py)
• Breaks incoming prompts into tasks.
e. Scheduler (blastai/scheduler.py) + Resource Manager (blastai/resource_manager.py)
• Allocates CPU/IO resources, parallelizes tasks across workers.
f. Executor (blastai/executor.py)
• Drives browser automation (e.g. headless browser), invokes LLM calls to external API or local model.
g. Cache (blastai/cache.py)
• Caches past prefixes/responses to reduce external calls.
h. Tools (blastai/tools.py)
• Encapsulates browser‐specific or other “tool” interfaces.
i. Logging (blastai/logging_setup.py) and Utils (blastai/utils.py)
j. Frontend UI (blastai/frontend/)
• Next.js app that interacts with the API via fetch/websockets for streaming.
k. Website (website/)
• Separate Next.js app purely for marketing/documentation.
l. External Services:
• OpenAI (or other LLM)
• Headless browser environments (Playwright/Puppeteer)
Architectural patterns and design principles
• Layered architecture: API layer → Orchestration (Engine/Planner) → Scheduling/Resource management → Execution → External backends (LLM + browser).
• Hexagonal/“ports and adapters” flavor: Modules interact via well-defined interfaces (cache adapter, tool adapter, resource adapter).
• Concurrency and streaming: event-driven, non-blocking IO for real-time streaming.