SAG

https://github.com/user-attachments/assets/ac805e3c-ab52-4857-bef6-2865f3831b2f

Contents

---

Project

Changelog

See CHANGELOG.md for release history and version-specific changes.

SAG in one minute

SAG is not a fusion of traditional RAG and GraphRAG. It is an original retrieval architecture that replaces both.

Through event-entity indexing and query-time dynamic hyperedges, SAG delivers semantic retrieval and relational reasoning in one system, without maintaining two RAG systems or merging two retrieval paths.

Experiments on HotpotQA, 2WikiMultiHopQA, and MuSiQue show that SAG achieves the best retrieval and end-to-end QA performance on every benchmark, establishing a new state of the art for RAG.

This project is a complete knowledge base application for individuals and Agents built on SAG:

sources and documents → structured knowledge → search and source tracing → cited Agent answers → reuse through API or MCP

Upload a document once. SAG parses it, splits it into chunks, embeds it, extracts events and entities, and keeps every retrieval result connected to the original text. You can then search across sources, inspect the event-entity graph, ask questions with citations, or expose the same knowledge to another application.

Capability	What it gives you
Knowledge ingestion	File and web sources, document parsing, chunking, embedding, event/entity extraction, background processing
Search	Cross-source or source-scoped retrieval with Fast (vector / multi_es_fast), Precise (multi), and optional JEV reranking (multi_jev) modes
Source tracing	Open any result or citation back to the exact original chunk
Knowledge graph	Inspect events, entities, and their queryable associations
Agent chat	Multi-turn answers grounded in selected sources, with clickable citations
Integration	Self-hosted REST/OpenAPI, OpenAI-compatible chat, MCP, and the zleap-sag Python package

The product is deliberately local-first and single-user. It starts with SQLite and LanceDB, requires no external database, and keeps a clear path to PostgreSQL/pgvector and other production backends.

---

Technology

Paper

SAG: SQL-Retrieval Augmented Generation with Query-Time Dynamic Hyperedges Yuchao Wu*, Junqin Li, XingCheng Liang, Yongjie Chen, Yinghao Liang, Linyuan Mo, and Guanxian Li

Read the paper · Reproduce the benchmark

An original third architecture

Traditional dense RAG retrieves chunks mainly by semantic similarity. GraphRAG adds offline graph construction, but pays for triple extraction, entity merging, relation normalization, global maintenance, and difficult incremental updates.

SAG does not wrap those two systems. It replaces that choice with its own data model and execution path:

chunk → one semantically complete event
chunk → multiple indexing entities
event ↔ entities → one latent hyperedge

• Event carries the complete meaning of a chunk. It is not fragmented into independent triples.
• Entity is a lightweight index and expansion point, not a replacement for the event's meaning.
• Query-time dynamic hyperedge is created locally when SQL joins events that share entities around the current query. SAG does not pre-build or globally maintain those hyperedges.
• Original evidence remains the output boundary. Selected events always map back to source chunks for generation and citation.

The semantic and structural paths inside SAG are native parts of the SAG pipeline. They are not a traditional RAG service and a GraphRAG service running side by side.

How retrieval works

Offline indexing

1. Parse a document into semantically coherent chunks.
2. Extract one event and multiple entities from each chunk in parallel.
3. Persist chunks, events, entities, and event-entity associations to relational storage.
4. Persist chunk, event, and entity representations to vector/full-text indexes.

Online retrieval

1. Find seed entities and events using semantic and lexical signals.
2. Use SQL joins over shared entities to expand from seed events into a local candidate space.
3. Instantiate only the hyperedges relevant to this query; no global graph traversal or rebuild is required.
4. Select the strongest event and direct-chunk candidates, deduplicate them, and return the original evidence chunks.

This makes incremental writes natural: a new chunk adds its own event, entities, and associations without recomputing a global graph.

A new SOTA for RAG

Under the same BGE-Large-EN-v1.5 embedding and Qwen3.6-Flash LLM configuration, SAG achieves the best retrieval and end-to-end QA performance on every benchmark across HotpotQA, 2WikiMultiHopQA, and MuSiQue.

• Across the three datasets, SAG averages 90.07%/72.96% in Recall@5 and F1, outperforming the strongest baseline for each metric by 6.79/4.33 percentage points, respectively.
• On the most challenging MuSiQue dataset, SAG outperforms the strongest baseline for each metric by 11.52/7.01 percentage points in Recall@5 and F1, respectively.

Full results:

See the paper and SAG-Benchmark for the full method and reproduction scripts.

---

User Guide

Desktop app (easiest)

Download the latest desktop installer from GitHub Releases:

Platform	Download	Update behavior
macOS 15+, Apple Silicon	SAG-*-mac-arm64.dmg	Signed and notarized; in-app updates require separate download and install confirmation
Windows 10/11, x64	SAG-Setup-*-win-x64.exe	Unsigned for now; Windows may show an unknown-publisher warning; in-app updates require separate download and install confirmation

The desktop app bundles the Web workspace and local knowledge backend, so users do not need to install Python, Node.js, or a database. Application updates preserve the knowledge base and uploads in the operating system's application-data directory. Release checksums are published as SHA256SUMS.txt.

If SAG detects incompatible legacy knowledge data, it leaves that data unchanged until you confirm a backup and a fresh workspace. SAG does not automatically migrate or merge the old knowledge base; upload your documents again after setup. The backup remains available for manual recovery. Accounts and model settings are preserved, while previous knowledge bases, documents, agents, conversations and related tasks do not appear in the new workspace. Current-format workspaces continue using their existing data directories.

Quick start (Docker, self-hosted)

Requirements: Docker Desktop, or Docker Engine with Compose v2.

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

No API key, Python runtime, Node runtime, or external database is required to boot the application. When both services are healthy, open:

• Web application: http://localhost:3000
• API documentation: http://localhost:8000/docs

On first launch:

1. Enter your name to create or restore the local identity.
2. Choose 302.AI or DeepSeek quick setup, or open Settings → Models to configure your model connections.
3. Create a source, upload documents, and wait until their status is Ready.
4. Search, open the original source, or start a cited conversation.

DeepSeek uses Flash in non-thinking mode. Either setup supports embeddings from 302.AI, Zhipu, or Alibaba Cloud Bailian; enter a separate Key when using a different provider.

The UI and services still start without model credentials. Embeddings are required for indexing/vector retrieval; the LLM is required for event extraction, query understanding, and generated answers.

Model settings precedence

SAG_LLM_* values in Docker Compose or .env provide the initial model configuration. After an administrator saves model settings in the web UI, the persisted Settings value is used for subsequent extraction and generation jobs without a restart.

New model setup suggests qwen3.8-flash for generation and Qwen/Qwen3-Embedding-4B for embeddings. Upgrades preserve saved model settings and explicit environment values; deployments without an explicit generation model retain the existing runtime default qwen3.6-flash. When upgrading an existing BGE index, retain SAG_EMBEDDING_MODEL=bge-large-en-v1.5. To switch models, wait for existing indexed documents to finish deleting, change the model, then import them again.

To make the deployment configuration mandatory, set SAG_LOCK_LLM_CONFIG=true. SAG then shows the generation fields as locked in Settings and continues to use the SAG_LLM_* values. Change Docker Compose or .env and recreate the API container to update a locked configuration. API keys remain deployment-managed and are never returned by the Settings API.

For separate chat and query endpoints, enable Chatbot LLM or Query embedding in the same Models page. Both are optional and leave document extraction/indexing on the original connections. Query embeddings share the original model and vector dimensions. See optional chatbot connections for deployment settings, credential storage, and recovery.

Select OpenAI-compatible, then choose the Responses API format for original generation or the optional chatbot LLM to use OpenAI-compatible, Azure, or Bedrock Responses endpoints. See Responses API setup for endpoint configuration, reasoning controls, authentication, and verification.

Use Test to check an unsaved original or optional model connection before saving it. Success shows a green check with the model or embedding dimensions; failure shows a red error. Testing does not save the draft. Successful optional connection saves apply to subsequent operations, while operations already running keep their captured configuration. During background document processing, queries can reuse an initialized compatible engine to reduce waiting. See optional chatbot connections for the runtime details.

Import knowledge

Create a source and add Markdown, text, PDF, Office, or other supported documents. SAG normalizes documents to Markdown, then runs chunking, embedding, event extraction, and entity extraction in the background.

File uploads show actual transfer progress. The document list and details show the current processing stage and available chunk counts (for example, “Processed 810 / 2,033 chunks”), without an overall processing percentage. A document is ready to search when its status becomes Ready.

PDF files use MinerU when it is configured and fall back to local MarkItDown when it is unavailable or fails. Other Office and text formats use MarkItDown by default.

PDF parsing also supports a self-hosted MinerU 4.x V1 API (mineru-kit api-server). Configure SAG_MINERU_PROVIDER=self_hosted, SAG_MINERU_BASE_URL, and SAG_DOCUMENT_PARSER=auto or mineru using .env.example. Local or private-network endpoints also require SAG_MINERU_ALLOW_PRIVATE_BASE_URL=true. Recreate the API container after deployment changes. Previously saved parser/MinerU settings override environment defaults; update those saved values through authenticated PUT /api/v1/system/model-config and check the effective configuration before importing PDFs.

You can also switch the parsing method to AnyDoc in settings (or set SAG_DOCUMENT_PARSER=anydoc): docx/pptx/epub/pdf/csv are converted on this machine by AnyDoc, nothing is uploaded, and no hosted OCR runs. XLS/XLSX retain local MarkItDown conversion to preserve Excel record groups and searchable chunks; the actual parser is recorded. Only files explicitly rejected as unsupported fall back to MarkItDown; other conversion errors are reported as failures. CSV is first decoded with SAG's encoding detection and normalized to UTF-8 before AnyDoc sees it, so non-UTF-8 Chinese CSV does not turn into mojibake. A scanned or image-only PDF is reported as needing OCR for the whole file (with page numbers) — switch to a configured MinerU and reprocess it; no partial text is cached. The default auto behaviour is unchanged.

Search and verify the source

Search across sources or restrict the query to selected sources. Without an explicit selection, global search and default Agent retrieval use up to 16 candidate sources by default. Use @ to target the sources you need. Every result can open the original chunk beside the ranked result, so retrieval quality is inspectable before an Agent uses it.

Ask with citations

The Agent searches the knowledge sources in the current scope, streams the answer, and attaches clickable citations. The same conversation path is also available through an OpenAI-compatible endpoint.

Select sources with @ to narrow a question's knowledge scope. Each question keeps its selected-source badges in conversation history, and Retry reuses that saved scope. The badges show the selected search scope; the answer's citations show the evidence actually used. See source scope in chat history.

Use New conversation in the sidebar to open a blank draft from any page. The draft stays selected when returning to chat, even while an older conversation finishes generating. Existing conversations remain in history; a new thread is saved when you send the first question. SAG generates one answer at a time, so wait for the ongoing answer to finish or stop it before sending in the new draft.

Explore mode

Explore mode unfolds the entire knowledge base into an interactive knowledge universe. Search events and entities, travel through their relationships, and open event details or original sources without leaving the same view.

Explore the event-entity graph

Switch a source from list view to graph view to inspect the events, entities, and associations produced by the SAG index.

MCP guide

The recommended path is two steps: CLI mounts the MCP, Skill teaches the Agent how to explore it. Together they give you a complete knowledge retrieval setup with zero hand-edited config.

Step 1: mount MCP with the CLI

@zleap-ai/sag-cli is the official command-line client. It auto-discovers your local Docker SAG container, verifies the MCP works, and wires it into Codex or Claude Code — for the local Docker path no JWT is needed.

Install (Node.js ≥ 20.19):

npm install --global @zleap-ai/sag-cli

Wire the MCP in one command:

sag mcp test                     # verify the SAG MCP is reachable
sag agent connect codex          # mount into Codex
sag agent connect claude-code    # or mount into Claude Code
sag agent status                 # see what's wired

For a remote SAG instance (no local Docker), sign in from the terminal first:

sag profile add prod https://sag.example.com
sag profile use prod
sag auth login --name "Your name" # signs in to SAG directly
sag agent connect claude-code

The CLI never writes your JWT into an Agent's config file, stores tokens in the OS keychain when available, and only removes MCP entries it created itself. Preview any write with --dry-run. Full guide: SAG CLI User Guide.

Step 2: install the Skill

The Skill ships in @zleap-ai/sag-cli. Copy it into your Agent's skills directory:

# Claude Code
SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge

# Codex
SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge

Manual mounting (fallback)

If you can't install the CLI, open Settings → Integrations → Knowledge MCP in SAG, pick HTTP or local command, and paste the copied block into your Agent's MCP config file yourself. The HTTP snippet already includes the current JWT and exposes all sources by default; scope it with source_id when needed.

Use SAG in DeepSeek Harness

Connect your SAG knowledge base to DeepSeek Harness with dsh-sag. The current plugin, dsh-sag 0.2.0, supports DeepSeek Harness 0.2.0-rc.2.

Start SAG. After dsh-sag 0.2.0 is published to npm, install and run the plugin:

dsh plugin --profile web add @zleap-ai/[email protected]
dsh plugin --profile web exec dsh-sag doctor
dsh --profile web

Ask dsh: “Search SAG for the upload limit and cite the original text.” See the plugin usage guide for connection options and supported capabilities.

Use SAG as a model (OpenAI-compatible)

SAG exposes an OpenAI Chat Completions endpoint with the same retrieval and citation behavior as the built-in chat:

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?"}]}'

The response is a standard chat.completion with an additional sag.citations field; standard clients ignore unknown fields. Set "stream": true to receive SSE chunks.

Use SAG as a Dify external knowledge base

SAG can connect to Dify's Connect to an External Knowledge Base feature through a dedicated compatibility endpoint, with no Dify source-code changes. For the API key, Docker network, Source ID, and Dify console configuration, see docs/dify-integration.en.md.

Operate and update

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

Default persistence:

Runtime	Application metadata	Knowledge engine	Location
Docker default	SQLite	SQLite + LanceDB	Docker volume sagdata
Local development	SQLite	SQLite + LanceDB	apps/api/.data/
PostgreSQL override	PostgreSQL	PostgreSQL + pgvector	pgdata and sagdata volumes

docker compose down preserves data. docker compose down -v permanently deletes the database, knowledge index, and uploaded files.

Network and production safety

The default Compose configuration binds ports 3000 and 8000 to 127.0.0.1 and uses SAG_AUTH_MODE=local: the name is a local identity, not password authentication. Do not expose this default mode to an untrusted network.

For custom ports or a trusted LAN address:

cp .env.example .env
# Edit BIND_ADDRESS, WEB_PORT, API_PORT, SAG_CORS_ORIGINS, and NEXT_PUBLIC_API_BASE.
# For remote access, also set SAG_AUTH_MODE=password and keep SAG_ALLOW_REGISTRATION=false.
docker compose up -d --build

On first launch, password mode guides you through creating an email and password. Later sign-ins require both credentials and never fall back to a name or the first user. SAG_ALLOW_REGISTRATION=false still permits the first credential account, then closes registration.

NEXT_PUBLIC_API_BASE is compiled into the web image, so changing it requires --build. A server deployment should also use a strong SAG_SECRET_KEY, HTTPS, and protection such as VPN, IP allowlisting, or reverse-proxy rate limiting. The current sag auth login --name command is for local mode; with password mode, sign in through the web UI first and provide the issued token to the CLI through SAG_TOKEN.

---

Developer Guide

System boundaries

SAG has a separated Next.js frontend and FastAPI backend. The backend is a reference application built on the public zleap-sag Python engine. You can reuse the complete backend from another frontend, or embed zleap-sag directly in a Python service of your own.

Repository map

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
deploy/                     Deployment initialization assets
integrations/dsh-sag/       Independently published DeepSeek Harness plugin and embedded runtime
docs/assets/readme/         README screenshots and diagrams

The central dependency rule is simple: application code reaches the engine through apps/api/sag_api/sag/; the engine does not know about FastAPI, the Web UI, users, conversations, or citations.

Local development

Start the backend and frontend in separate terminals from the repository root.

# 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

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

Useful checks:

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

Desktop client

The Electron client packages the same Next.js application together with the local FastAPI backend. Desktop development, target-specific release builds, signing, update configuration, and data locations are documented in apps/desktop/README.md.

Use zleap-sag directly

zleap-sag is the continuously maintained Python engine behind the SAG application. Distribution name: zleap-sag; import path: zleap.sag; Python: 3.11+; license: MIT. The application currently requires zleap-sag==0.15.0.

Install the zero-infrastructure local stack:

pip install zleap-sag==0.15.0

With an existing knowledge.md and working model credentials, run the complete ingest → extract → search lifecycle:

import asyncio
from pathlib import Path

from zleap.sag import DataEngine, EngineConfig
from zleap.sag.config import EmbeddingConfig, LLMConfig
from zleap.sag.pipeline import SearchOptions, SearchRequest, SearchScope


async def main() -> None:
    config = EngineConfig(
        storage_mode="normal",
        llm=LLMConfig(
            api_key="sk-...",
            base_url="https://your-openai-compatible-host/v1",
            model="qwen3.8-flash",
        ),
        # When api_key/base_url are omitted, embedding reuses the LLM endpoint.
        embedding=EmbeddingConfig(model="Qwen/Qwen3-Embedding-4B"),
        language="en",
    )

    # One DataEngine instance represents one logical data source.
    async with DataEngine(config, data_source_id="knowledge-demo") as engine:
        chunks = await engine.ingest(Path("knowledge.md"))
        events = await engine.extract(chunks)
        request = SearchRequest(
            query="Why is SAG effective for multi-hop retrieval?",
            scope=SearchScope(data_source_ids=(chunks.data_source_id,)),
            options=SearchOptions(strategy="full_expand", top_k=5, return_type="chunk"),
        )
        result = await engine.search(request)

        print(chunks.chunk_count, events.event_count)
        for hit in result.chunks:
            print(hit.content[:200])


asyncio.run(main())

Local storage is created automatically under ./.zleap/. Add that directory to .gitignore.

Configuration

Use one configuration style, not both:

Style	Construction	Best for
Parameter injection	EngineConfig(storage_mode="normal", llm=..., embedding=...)	Libraries, notebooks, explicit application wiring
Environment	EngineConfig.from_env() or from_env(env_file=".env")	Containers and 12-factor services

Minimal environment configuration:

export SAG_STORAGE_MODE=normal
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-openai-compatible-host/v1
export LLM_MODEL=qwen3.8-flash
export EMBEDDING_MODEL=Qwen/Qwen3-Embedding-4B

from zleap.sag import EngineConfig

config = EngineConfig.from_env()

EngineConfig(...) does not read environment variables implicitly. Use explicit parameters or from_env(). A separate embedding endpoint can be set with EmbeddingConfig(api_key=..., base_url=..., model=...).

Public DataEngine API

API	Purpose
await engine.start()	Initialize connections; local SQLite/LanceDB schema is created automatically
await engine.aclose()	Close engine resources; handled automatically by async with
await engine.parse(source, options=None)	Parse a FileSource, TextSource, or other SourceInput into a ParsedSource without persisting it
await engine.chunk(parsed, options=None)	Chunk a ParsedSource into a ChunkSet without persisting it
await engine.ingest(source, ...)	Parse, chunk, embed, and persist a path, text, or SourceInput; return a ChunkSetRef
await engine.extract(target, options=None)	Extract and persist events/entities from a ChunkSetRef or PersistedChunkSelector; return an EventSetRef
await engine.search(request)	Search with an explicit SearchRequest (query, scope, options); return a SearchResult with chunks, events, and stats
await engine.init_schema()	Idempotently initialize production schemas; not needed for the default local stack

Pipeline request and result types are available from zleap.sag.pipeline: ParsedSource, ChunkSet, ChunkSetRef, EventSetRef, SearchRequest, and SearchResult. All engine exceptions derive from SagError in zleap.sag.exceptions, so application boundaries can catch one base type.

Retrieval modes

UI label	App/API strategy	Implementation
Fast (vector)	vector	Direct retrieval by semantic similarity for a faster response
Fast (multi_es-fast)	multi_es_fast	BM25 entity recall and event multi-hop retrieval, skipping LLM reranking
Precise	multi	Combines entity relationships with LLM reranking for more complete results
JEV reranking	multi_jev	Scores recalled and graph-expanded evidence through an independent JEV service

These are the application/API strategy names; the application maps multi to the Python engine's full_expand and multi_es_fast to pruned_expand_rff. Availability depends on storage capabilities: multi_es_fast requires lexical search support.

Configure 302.AI, TypeSafe, or a custom JEV service in Settings → Knowledge → Retrieval (default model: jev-latest, separate API key), then select JEV reranking. Saving the service alone does not enable it. The default deadline is 30 seconds; failures return an error unless coarse fallback is enabled.

Supported on LanceDB and Elasticsearch; pgvector is currently unsupported. PostgreSQL relational storage can use JEV with a supported vector backend. Existing retrieval settings remain until JEV is selected; documents do not need reindexing. See the benchmark results and cost estimates.

Storage backends

Deployment	Relational storage	Vector storage	Package extra
Local default	SQLite	LanceDB	none
Single database	PostgreSQL	pgvector	zleap-sag[postgres]
Production split	MySQL/PostgreSQL/OceanBase	Elasticsearch	zleap-sag[mysql], [postgres], [es]
Single database	OceanBase 4.3.3+	OceanBase vector	zleap-sag[mysql]

Changing EngineConfig changes the backend without changing ingest/extract/search calls. Each DataEngine instance owns its connections and resources; close it with async with or aclose().

For the full package configuration, extras, examples, and changelog, see the zleap-sag package page.

Build your own frontend with the SAG backend

A browser cannot import a Python package directly. A custom frontend should call a Python HTTP service that owns DataEngine. This repository's FastAPI backend is that reference service, and it is already separated from the Next.js UI.

The self-hosted API is available after starting SAG:

Entry	Address
API base	http://localhost:8000/api/v1
Interactive OpenAPI	http://localhost:8000/docs
OpenAPI schema	http://localhost:8000/openapi.json
MCP Streamable HTTP	http://localhost:8000/mcp/

This is a self-hosted API, not a hosted public cloud API. In the default local mode, most routes use a SAG JWT issued after name login:

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

Copy access_token from the response and send it as:

Authorization: Bearer <SAG_TOKEN>

With SAG_AUTH_MODE=password, create the first credential through POST /auth/register, then sign in with email and password:

curl -s http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"<YOUR_PASSWORD>"}'

API map

Area	Main routes	Purpose
System	GET /system/health, /system/ready, /system/capabilities	Health and active engine capabilities
Identity	POST /auth/login, GET /auth/me	Local identity and JWT
Sources	GET/POST /sources, GET/PATCH/DELETE /sources/{id}	Source lifecycle
Documents	/sources/{id}/documents and /documents/ingest	File upload, continuous text/message ingestion, reprocessing, deletion
Search	POST /search, POST /sources/{id}/search	Global or source-scoped vector/multi retrieval
Graph	GET /sources/{id}/entities, /sources/{id}/graph	Event-entity inspection
Agents	/agents, /threads, /ask	Agent configuration, conversations, SSE runs, citations
OpenAI-compatible	POST /openai/{agent_id}/chat/completions	Use any SAG Agent as a cited model, streamed or non-streamed
MCP	/mcp/ or /mcp/?source_id={id}	Expose the whole knowledge base or one source to an MCP host

Create a source, ingest text, and search it:

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}'

Document ingestion is processed by the background job queue. Check the returned document status or its job before expecting search results.

For a frontend served from another origin, add it to SAG_CORS_ORIGINS. If the API address changes, rebuild the Web image with the matching NEXT_PUBLIC_API_BASE.

PostgreSQL/pgvector deployment

The optional production override moves application metadata and engine storage to PostgreSQL/pgvector:

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

Set real SAG_CORS_ORIGINS and NEXT_PUBLIC_API_BASE values before server deployment. Back up both pgdata and sagdata before upgrades.

---

Contributing and License

• Contribution workflow: CONTRIBUTING.md
• Python engine: zleap-sag on PyPI
• Paper reproduction: Zleap-AI/SAG-Benchmark

SAG is released under the MIT License.

---

Community

Join the SAG community on Discord or WeChat to connect with maintainers and other users.