SAG

https://github.com/zleap-ai/sag
Admin
SAG (SQL-Driven Smart Auto Graph Engine) is a new generation SQL-driven RAG engine that...
Tokens:4,817
Snippets:61
Trust Score:5.4
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install zleap-sag

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Install the library via pip to access the local stack.

```bash
pip install zleap-sag
```

--------------------------------

### Start Backend and Frontend

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Commands to initialize and run the API and Web services in separate terminals.

```bash
# Terminal 1: API at http://localhost:8000
cd apps/api
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
uvicorn sag_api.main:app --reload
```

```bash
# Terminal 2: Web at http://localhost:3000
cd apps/web
npm install
npm run dev
```

--------------------------------

### Deploy with PostgreSQL/pgvector

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Configure environment variables and start the services using Docker Compose.

```bash
cp .env.example .env
openssl rand -hex 32   # set SAG_SECRET_KEY
openssl rand -hex 24   # set POSTGRES_PASSWORD

docker compose -f compose.yaml -f compose.postgres.yaml config
docker compose -f compose.yaml -f compose.postgres.yaml up -d --build
```

--------------------------------

### Deploy SAG with Docker

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Use Docker Compose to build and start the SAG services locally.

```bash
git clone https://github.com/Zleap-AI/SAG.git
cd SAG
docker compose up -d --build
```

--------------------------------

### Install SAG Skill for Agents

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Copy the SAG skill directory to your agent's local skills configuration path.

```bash
# Claude Code
cp -R skills/sag ~/.claude/skills/sag-knowledge

# Codex
cp -R skills/sag ~/.codex/skills/sag-knowledge
```

--------------------------------

### Configure via Environment Variables

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Set up the engine using environment variables instead of explicit parameters.

```bash
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-openai-compatible-host/v1
export LLM_MODEL=qwen3.6-flash
export EMBEDDING_MODEL=bge-large-en-v1.5
```

```python
from zleap.sag import EngineConfig

config = EngineConfig.from_env()
```

--------------------------------

### Run DataEngine Lifecycle

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Demonstrates the full ingest, extract, and search workflow using the DataEngine class.

```python
import asyncio

from zleap.sag import DataEngine, EngineConfig
from zleap.sag.config import EmbeddingConfig, LLMConfig


async def main() -> None:
    config = EngineConfig(
        llm=LLMConfig(
            api_key="sk-...",
            base_url="https://your-openai-compatible-host/v1",
            model="qwen3.6-flash",
        ),
        # When api_key/base_url are omitted, embedding reuses the LLM endpoint.
        embedding=EmbeddingConfig(model="bge-large-en-v1.5"),
        language="en",
    )

    # One DataEngine instance represents one logical data source.
    async with DataEngine(config) as engine:
        ingest = await engine.ingest("knowledge.md")
        extract = await engine.extract()
        result = await engine.search(
            "Why is SAG effective for multi-hop retrieval?",
            strategy="multi",
            top_k=5,
        )

        print(ingest.chunk_count, extract.event_count)
        for section in result.sections:
            print(section.get("content", "")[:200])


asyncio.run(main())
```

--------------------------------

### Manage Sources and Ingest Documents

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Create a source, ingest text content, and perform a search query using the API.

```bash
BASE=http://localhost:8000/api/v1
TOKEN=<SAG_TOKEN>

SOURCE_ID=$(curl -s -X POST "$BASE/sources" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Product docs"}' | jq -r .id)

curl -s -X POST "$BASE/sources/$SOURCE_ID/documents/ingest" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"SAG","text":"SAG uses event-entity indexing and query-time dynamic hyperedges."}'

curl -s -X POST "$BASE/sources/$SOURCE_ID/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query":"How does SAG retrieve knowledge?","strategy":"multi","top_k":5}'
```

--------------------------------

### Configure SAG Network Settings

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Steps to customize environment variables for network binding and port configuration. Rebuilding is required after changing NEXT_PUBLIC_API_BASE.

```bash
cp .env.example .env
# Edit BIND_ADDRESS, WEB_PORT, API_PORT, SAG_CORS_ORIGINS, and NEXT_PUBLIC_API_BASE.
docker compose up -d --build
```

--------------------------------

### Run project checks

Source: https://github.com/zleap-ai/sag/blob/main/CONTRIBUTING.md

Execute linting, type checking, and unit tests for both backend and frontend components.

```bash
cd apps/api && ruff check sag_api/ sag_agent/ tests/ && python -m pytest -q
cd apps/web && npm run typecheck && npm run lint && npm run test:unit && npm run build
```

--------------------------------

### Run Development Checks

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Commands for running tests, linting, and build verification.

```bash
cd apps/api && pytest
cd apps/api && ruff check .
cd apps/web && npm run typecheck
cd apps/web && npm run build
```

--------------------------------

### POST /sources

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Creates a new data source for document ingestion and search.

```APIDOC
## POST /api/v1/sources

### Description
Creates a new source container for documents.

### Method
POST

### Endpoint
/api/v1/sources

### Request Body
- **name** (string) - Required - The name of the new source.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created source.
```

--------------------------------

### Manage SAG Docker Services

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Common commands for monitoring, restarting, and updating the SAG application environment.

```bash
docker compose ps                  # api and web should be healthy
docker compose logs -f api web     # follow logs
docker compose restart             # restart services
docker compose down                # stop and keep all data

git pull --ff-only                 # update the source checkout
docker compose up -d --build       # rebuild without deleting volumes
```

--------------------------------

### View Repository Structure

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Displays the directory layout of the SAG project.

```text
apps/
├── web/                    Next.js 15 + React 19 product UI
├── desktop/                Electron shell, packaging, and local runtime lifecycle
└── api/
    ├── sag_api/
    │   ├── api/v1/         FastAPI HTTP routes and serialization
    │   ├── connectors/     File/web source connectors and registry
    │   ├── parsing/        MarkItDown and MinerU normalization
    │   ├── jobs/           Background ingest → extract state machine
    │   ├── sag/            The only application adapter importing zleap-sag
    │   ├── generation/     Retrieved evidence → streamed cited answer
    │   ├── mcp/            Knowledge MCP server and HTTP mount
    │   ├── services/       Application/domain orchestration
    │   └── tools/          Built-in and remote MCP Agent tools
    └── sag_agent/          Framework-independent Agent runtime core
skills/sag/                 Agent Skill for exploring SAG through MCP
deploy/                     Deployment initialization assets
docs/assets/readme/         README screenshots and diagrams
```

--------------------------------

### Authenticate with the SAG API

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Use this command to obtain a JWT for subsequent API requests.

```bash
curl -s http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"Developer"}'
```

--------------------------------

### POST /auth/login

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Authenticates a user and returns a JWT access token required for most API operations.

```APIDOC
## POST /api/v1/auth/login

### Description
Authenticates a user by name and returns a JWT access token.

### Method
POST

### Endpoint
/api/v1/auth/login

### Request Body
- **name** (string) - Required - The name of the user to authenticate.

### Request Example
{
  "name": "Developer"
}

### Response
#### Success Response (200)
- **access_token** (string) - The JWT token used for authorization.
```

--------------------------------

### POST /api/v1/openai/<AGENT_ID>/chat/completions

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Sends a chat completion request to a specific agent. The response includes standard chat completion fields plus a sag.citations field.

```APIDOC
## POST /api/v1/openai/<AGENT_ID>/chat/completions

### Description
Sends a chat completion request to the specified agent. This endpoint is compatible with the OpenAI Chat Completions API and supports streaming via the stream parameter.

### Method
POST

### Endpoint
/api/v1/openai/<AGENT_ID>/chat/completions

### Parameters
#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Request Body
- **messages** (array) - Required - A list of message objects with role and content.
- **stream** (boolean) - Optional - Set to true to receive SSE chunks.

### Request Example
{
  "messages": [{"role": "user", "content": "What is this material about?"}]
}

### Response
#### Success Response (200)
- **chat.completion** (object) - Standard OpenAI chat completion response.
- **sag.citations** (object) - Additional field containing citation information.
```

--------------------------------

### DataEngine.ingest

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Parses a document, chunks it, generates embeddings, and persists the data.

```APIDOC
## DataEngine.ingest(path, ...)

### Description
Parses one document, chunks it, embeds it, and persists chunks and vectors to the configured storage backend.

### Parameters
- **path** (str) - Required - The file path to the document to be ingested.

### Returns
- **IngestResult** - Contains metadata such as chunk_count.
```

--------------------------------

### Query SAG via OpenAI-compatible API

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Use curl to send a chat completion request to the SAG agent endpoint. Ensure the Authorization header includes a valid SAG_JWT.

```bash
curl -s http://localhost:8000/api/v1/openai/<AGENT_ID>/chat/completions \
  -H "Authorization: Bearer <SAG_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What is this material about?"}]}'
```

--------------------------------

### DataEngine.chunk

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Parses and chunks a path or raw string without persisting it.

```APIDOC
## DataEngine.chunk(source)

### Description
Utility method to parse and chunk content without saving to the database.

### Parameters
- **source** (str) - Required - The path or raw string content to chunk.

### Returns
- **ChunkResult** - The resulting chunks.
```

--------------------------------

### POST /sources/{id}/documents/ingest

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Ingests text documents into a specific source for indexing.

```APIDOC
## POST /api/v1/sources/{id}/documents/ingest

### Description
Ingests text content into the specified source. This process is handled by a background job queue.

### Method
POST

### Endpoint
/api/v1/sources/{id}/documents/ingest

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the source.
```

--------------------------------

### POST /sources/{id}/search

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Performs a search query within a specific source using vector or multi-retrieval strategies.

```APIDOC
## POST /api/v1/sources/{id}/search

### Description
Executes a search query against a specific source.

### Method
POST

### Endpoint
/api/v1/sources/{id}/search

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the source.

### Request Body
- **query** (string) - Required - The search query string.
- **strategy** (string) - Required - The retrieval strategy (e.g., 'vector', 'multi').
- **top_k** (integer) - Optional - The number of results to return.
```

--------------------------------

### Set Authorization Header

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Include the access token in the Authorization header for authenticated requests.

```http
Authorization: Bearer <SAG_TOKEN>
```

--------------------------------

### DataEngine.search

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Performs a semantic search against the ingested data using specified strategies.

```APIDOC
## DataEngine.search(query, strategy, top_k)

### Description
Searches the data source using either 'vector' (Fast) or 'multi' (Precise) strategies.

### Parameters
- **query** (str) - Required - The search query string.
- **strategy** (str) - Optional - Retrieval mode: 'vector' or 'multi'.
- **top_k** (int) - Optional - Number of results to return.

### Returns
- **SearchResult** - Contains sections and timing/statistics.
```

--------------------------------

### DataEngine.extract

Source: https://github.com/zleap-ai/sag/blob/main/README.md

Extracts and persists the event-entity index for the current data source.

```APIDOC
## DataEngine.extract()

### Description
Processes the ingested data to extract and persist the event-entity index.

### Returns
- **ExtractResult** - Contains metadata such as event_count.
```
Tokens:
Raw