isage-edge 0.2.4.13

SAGE Edge aggregator shell - mounts LLM gateway under an optional prefix

SAGE Edge

Lightweight FastAPI aggregator shell for mounting SAGE LLM Gateway

Overview

SAGE Edge is an optional aggregator shell that mounts the entire SAGE LLM Gateway application, providing:

• ✅ Gateway Mounting: Mount complete Gateway app (Control Plane, RAG Pipeline, Sessions) at / or custom prefix
• ✅ Path Preservation: Keep /v1/* endpoints stable (OpenAI-compatible)
• ✅ Health Endpoints: /healthz and /readyz at edge level
• ✅ Flexible Deployment: Optional component - Gateway works standalone without Edge

Boundary note:

• Framework-agnostic runtime logic is in sage.edge.core.
• sage.edge.app only handles FastAPI adaptation.
• Gateway app loading is explicit in sage.edge.server.
• Root package sage.edge exports only stable metadata (__version__).

Architecture

User Requests
     ↓
sage-edge (Port 8899)              ← Optional aggregator shell
     ↓ (mounts at / or custom prefix)
sage-llm-gateway (entire app)      ← Control Plane + RAG + Sessions + /v1/*
     ↓
LLM Engines (sageLLM, etc.)

What Edge Mounts:

• ✅ Control Plane management API
• ✅ OpenAI-compatible /v1/chat/completions, /v1/embeddings
• ✅ RAG Pipeline (retrieval, refinement, generation)
• ✅ Session Management (NeuroMem VDB/KV/Graph backends)
• ✅ Studio Backend routes

Installation

From PyPI (Recommended)

pip install isage-edge

From Source

git clone https://github.com/intellistream/sage-edge.git
cd sage-edge
pip install -e .

Quick Start

Default Usage (Mount at /)

# Start Edge server (mounts Gateway at /)
sage-edge --port 8899

# Gateway endpoints available directly
curl http://localhost:8899/v1/models
curl http://localhost:8899/healthz

Custom Prefix

# Mount Gateway under /llm prefix
sage-edge --port 8899 --llm-prefix /llm

# Gateway endpoints now at /llm/v1/*
curl http://localhost:8899/llm/v1/models
curl http://localhost:8899/healthz  # Edge health (root level)

Without LLM Gateway

# Start as minimal health check server
sage-edge --port 8899 --no-llm

Prerequisites

SAGE Edge requires the following packages (auto-installed):

• isage-llm-gateway>=0.1.0 - SAGE LLM Gateway
• isage-llm-core>=0.2.0 - Control Plane client
• isage-common>=0.2.0 - Common utilities (ports, paths)
• fastapi>=0.115.0 - Web framework
• uvicorn[standard]>=0.34.0 - ASGI server

Configuration

Environment Variables

# Edge server settings
SAGE_EDGE_HOST=0.0.0.0           # Bind interface (default: 0.0.0.0)
SAGE_EDGE_PORT=8899              # Port (default: 8899, from SagePorts.EDGE_DEFAULT)
SAGE_EDGE_LLM_PREFIX=/llm        # Mount prefix (default: /)
SAGE_EDGE_LOG_LEVEL=info         # Log level (debug, info, warning, error)

CLI Options

sage-edge --help

Options:
  --host TEXT          Host interface to bind (default: 0.0.0.0)
  --port INTEGER       Port to bind (default: 8899)
  --llm-prefix TEXT    Mount prefix for Gateway (default: /)
  --no-llm            Start without mounting Gateway
  --log-level TEXT     Log level (default: info)

Usage Examples

1. Production Deployment

# Mount Gateway at root, production settings
sage-edge \
  --host 0.0.0.0 \
  --port 8899 \
  --log-level warning

2. Multi-Service Setup

# Edge as reverse proxy with custom prefix
sage-edge \
  --port 8899 \
  --llm-prefix /api/llm

# Access:
# - Gateway: http://localhost:8899/api/llm/v1/*
# - Edge health: http://localhost:8899/healthz

3. Development Mode

# Verbose logging for debugging
sage-edge \
  --port 8899 \
  --log-level debug

API Endpoints

Edge-Level Endpoints

Endpoint	Method	Description
/healthz	GET	Health check (always available)
/readyz	GET	Readiness check (always available)

Response Example:

{
  "status": "ok",
  "service": "SAGE Edge",
  "llm_mounted": true,
  "llm_prefix": "/"
}

Gateway Endpoints (When Mounted)

Endpoint Pattern	Description
{prefix}/v1/chat/completions	OpenAI-compatible chat
{prefix}/v1/embeddings	OpenAI-compatible embeddings
{prefix}/v1/models	List available models
{prefix}/v1/management/*	Control Plane API
{prefix}/sessions/*	Session management

Note: {prefix} is / by default or custom value from --llm-prefix.

When to Use SAGE Edge

✅ Use Edge When:

• You need custom mount paths (e.g., /api/llm/v1/*)
• Deploying behind reverse proxy with path rewriting
• Want separated edge-level health checks
• Building multi-service aggregator

⚠️ Use Gateway Directly When:

• Default /v1/* paths are acceptable
• Simpler deployment preferred
• No custom prefix needed

Comparison: Edge vs Gateway

Feature	sage-edge	sage-llm-gateway
OpenAI /v1/*	✅ (via mount)	✅ (native)
Custom Prefix	✅	❌
Edge Health	✅ (/healthz, /readyz)	✅ (built-in)
Control Plane	✅ (mounted)	✅ (native)
RAG Pipeline	✅ (mounted)	✅ (native)
Session Mgmt	✅ (mounted)	✅ (native)
Deployment	Optional shell	Core service

Development

Running Tests

# Install dev dependencies
pip install -e .[dev]

# Run tests
pytest tests/ -v

# Run linting
ruff check src/
ruff format --check src/

Runtime Regression Baseline

• Issue #4 app/runtime tests:
  • tests/test_app.py
  • tests/test_server.py
• Issue #3 boundary tests:
  • tests/test_issue3_web_adapter_boundary.py
• ADR:
  • docs/adr/0001-fastapi-adapter-entry-boundary.md
• Validation:
  • ruff check src tests
  • pytest -q tests

Issue #2 boundary artifacts:

• Regression test: tests/test_issue2_boundary_decoupling.py
• ADR: docs/adr/0001-edge-service-algorithm-boundary.md

Project Structure

sage-edge/
├── src/sage/edge/
│   ├── __init__.py       # Stable metadata only
│   ├── _version.py       # Version info
│   ├── core.py           # Framework-agnostic runtime logic
│   ├── app.py            # FastAPI adapter
│   └── server.py         # CLI entrypoint
├── tests/                # Test suite
├── pyproject.toml        # Package config
└── README.md             # This file

Links

• Main Repository: SAGE Framework
• Gateway: isage-llm-gateway
• Documentation: SAGE Docs
• PyPI Package: isage-edge
• Issues: GitHub Issues

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

License

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

Acknowledgments

SAGE Edge is part of the SAGE framework developed by the IntelliStream team.

---

Questions? Open an issue on GitHub or check the documentation.