🌌 Universe

Welcome to Universe — a powerful, easy-to-use web server, embedder, and vector database designed for developers who want to work with embeddings and vector-based queries effortlessly. With Universe, you can "emit" (store) and "resonate" (query) with text-based "things" in a universe of your choice, leveraging the power of the latest embedding models from multiple providers.

Universe is built to be production-ready, highly configurable, and delightful to use. Whether you're building AI-powered applications, experimenting with vector databases, or just exploring the possibilities of embeddings, Universe has got you covered! 🚀

✨ Features

• Simple CLI Interface: Get started with just a few commands.
• Flexible Configuration: Use environment variables or CLI flags to configure the server explicitly.
• Multiple Embedding Providers: Choose between OpenAI, Voyage, or other providers for generating embeddings.
• Pluggable Storage: Keep things lightweight with the default directory-backed Vectra index, or use MySQL for server and Kubernetes deployments.
• Secure Authentication: Timing-safe bearer authentication, strict input bounds, rate limiting, and JSON-only API errors.
• Production Signals: Structured JSON logs, request IDs, Prometheus metrics, health and dependency-aware readiness endpoints.
• Safe Lifecycle: Validated startup configuration and graceful shutdown for both directory and MySQL storage.
• Web UI: A nonce-protected same-origin explorer with session-scoped credentials and safe text rendering.

📦 Installation

To install Universe globally, run:

npm i -g @shoprag/universe

This will make the universe CLI command available on your system.

🚀 Quick Start

After installation, configure the required credentials and start the service:

PROVIDER=voyage \
MODEL=voyage-4-large \
API_KEY=your-provider-key \
BEARER_TOKEN=a-long-random-service-token \
universe

Production startup fails closed when required configuration is missing. Store secrets in your deployment platform rather than shell history or source control.

🛠️ Usage

Universe provides a simple CLI to manage your server:

• Start the Server:

  universe

  Launches the server with the configured settings. The web UI can be accessed from a browser.

• Help:

  universe --help

  Displays all available options and commands.

• Custom Configuration:
  You can override default settings using CLI flags. For example:

  universe --port 3000 --log-level debug --provider openai --api-key sk-...

  Available flags:

  • --port <port>: Port to listen on (default: 8080)
  • --provider <provider>: Embedding provider (e.g., openai, voyage) (default: openai)
  • --api-key <key>: API key for the selected provider
  • --model <model>: Embedding model to use (provider-specific)
  • --base-url <url>: Optional embedding-provider base URL
  • --bearer-token <token>: Bearer token for authentication
  • --metrics-port <port>: Prometheus/health listener (default: 9091)
  • --log-level <level>: Log level (default: info)
  • --storage <backend>: Storage backend, either directory or mysql (default: directory)
  • --data-dir <dir>: Directory to store data (default: ./data)
  • --mysql-host <host>: MySQL host when using --storage mysql
  • --mysql-port <port>: MySQL port (default: 3306)
  • --mysql-user <user>: MySQL user
  • --mysql-password <password>: MySQL password
  • --mysql-database <database>: MySQL database
  • --mysql-table <table>: MySQL table for vectors (default: universe_items)
  • --mysql-connection-limit <limit>: MySQL connection pool limit (default: 10)
  • --log-requests: Log incoming requests (default: false)

🔧 Configuration

Universe is highly configurable:

• Environment Variables: Set variables in a .env file or directly in your environment. Key variables include:
  • PROVIDER: The embedding provider (e.g., openai, voyage)
  • API_KEY: API key for the selected provider
  • MODEL: Embedding model (provider-specific)
  • BASE_URL: Optional embedding-provider base URL
  • PORT, BEARER_TOKEN, LOG_LEVEL, STORAGE_BACKEND, DATA_DIR, LOG_REQUESTS
  • MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE, MYSQL_TABLE, MYSQL_CONNECTION_LIMIT
• CLI Flags: Override settings on the fly when starting the server. STORAGE=mysql is accepted as an alias for STORAGE_BACKEND=mysql. The MySQL settings also accept DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, and DB_TABLE aliases for deployment environments that already use those names. APP_ENV and RELEASE identify the runtime in logs and metrics.

For Voyage retrieval, Universe defaults to voyage-4-large at 2048 dimensions. Documents sent to /emit are embedded with input_type=document; /resonate queries use input_type=query, matching Voyage's retrieval guidance. Do not mix vectors from different embedding model generations in one universe. Create a new, versioned universe and switch consumers only after validating retrieval quality.

Operations endpoints

• GET /healthz: liveness and release identity; no authentication required.
• GET /readyz: verifies the selected storage backend; no authentication required.
• GET /metrics on METRICS_PORT: Prometheus process, HTTP, embedding, and storage signals. Keep this port cluster-internal.

Storage Backends

Universe uses directory storage by default. This keeps the original lightweight behavior and stores local Vectra indexes under DATA_DIR.

universe --storage directory --data-dir ./data

For deployments that need shared or managed persistence, use MySQL:

universe \
  --storage mysql \
  --mysql-host mysql.example.internal \
  --mysql-user universe \
  --mysql-password secret \
  --mysql-database universe

The MySQL backend creates the configured table automatically. It stores the text, vector JSON, and vector norm in regular MySQL rows, then computes cosine similarity in the application so the public API stays the same.

📡 API Documentation

Universe exposes a RESTful API for interacting with your universes. The API remains the same regardless of the embedding provider chosen.

Authentication

All requests must include a bearer token in the Authorization header:

Authorization: Bearer YOUR_BEARER_TOKEN

Endpoints

POST /emit

• Description: Emit (add) one or multiple things to a universe.
• Body:
  • universe (string, required): The universe name.
  • thing (object, optional): A single thing with text (required) and id (optional).
  • things (array, optional): An array of things, each with text and optional id.
  • replace (string, optional): Replace the thing with this ID.
• Response:

  { "status": "success" }

POST /resonate

• Description: Resonate (query) with a thing in a universe.
• Body:
  • universe (string, required): The universe name.
  • thing (string, required): The text to resonate with.
  • reach (number, optional): Number of results to return (default: 10).
• Response:

  { 
    "status": "success", 
    "results": [{ "closeness": number, "thing": string, "id": string }] 
  }

DELETE /thing/:universe/:id

• Description: Delete a specific thing from a universe.
• Parameters:
  • universe (string, required): The universe name.
  • id (string, required): The ID of the thing to delete.
• Response:

  { "status": "success" }

DELETE /universe/:universe

• Description: Delete all things from a universe.
• Parameters:
  • universe (string, required): The universe name.
• Response:

  { "status": "success" }

🤝 Contributing

We welcome contributions to Universe! If you have ideas, bug reports, or want to contribute code, please:

1. Check out the GitHub repository.
2. Open an issue or submit a pull request.

📄 License

Universe is licensed under the MIT License.