helix-gateway

HTTP gateway and gRPC backend service library for building query-based APIs.

Features

• gateway - HTTP server that translates REST requests to gRPC calls
• db - gRPC backend service implementation with handler routing

Both features are enabled by default.

Gateway Usage

Add to your Cargo.toml:

[dependencies]
helix-gateway = { version = "0.1", features = ["gateway"] }

Run the gateway:

#[tokio::main]
async fn main() -> eyre::Result<()> {
    helix_gateway::gateway::run().await
}

The gateway loads query definitions from introspect.json and forwards requests to the configured gRPC backend.

Introspection JSON Structure

The introspect.json file defines the available queries and their configurations:

{
  "queries": {
    "get_users": {
      "request_type": "READ",
      "parameters": {},
      "return_types": {},
      "embedding_config": null
    },
    "create_user": {
      "request_type": "WRITE",
      "parameters": {
        "name": "string",
        "email": "string"
      },
      "return_types": {
        "id": "string"
      }
    },
    "semantic_search": {
      "request_type": "READ",
      "parameters": {
        "query_text": "string",
        "limit": "number"
      },
      "return_types": {},
      "embedding_config": {
        "provider_config": {
          "provider": "openai",
          "config": {
            "model": "text_embedding_3_large"
          }
        },
        "embedded_variables": ["query_text"]
      }
    }
  },
  "schema": {}
}

Query Fields

Embedding Providers

When using vector search, configure embedding_config with one of these providers:

OpenAI

{
  "provider": "openai",
  "config": {
    "model": "text_embedding_3_large"
  }
}

Models: text_embedding_3_large, text_embedding_3_small, text_embedding_ada_002

Azure OpenAI

{
  "provider": "azure",
  "config": {
    "model": "text_embedding_3_large",
    "deployment_id": "your-deployment-id"
  }
}

Gemini

{
  "provider": "gemini",
  "config": {
    "model": "embedding_001",
    "task_type": "RETRIEVAL_DOCUMENT"
  }
}

Local

{
  "provider": "local",
  "config": {
    "url": "http://localhost:8699/embed"
  }
}

Start the gRPC server

use helix_gateway::db::{DbService, BackendServiceServer};
use tonic::transport::Server;

#[tokio::main]
async fn main() -> eyre::Result<()> {
    let db = MyDb::default();
    let service = DbService::new(db);

    Server::builder()
        .add_service(BackendServiceServer::new(service))
        .serve("0.0.0.0:50051".parse()?)
        .await?;

    Ok(())
}

Configuration

All settings are configured via environment variables with sensible defaults.

Gateway

gRPC Client

Embeddings