Skip to content

Latest commit

 

History

History
113 lines (84 loc) · 3.88 KB

index.md

File metadata and controls

113 lines (84 loc) · 3.88 KB

SyftHub Documentation

SyftHub is a registry and discovery platform for AI/ML endpoints — "GitHub for AI endpoints."


Getting Started

Doc Audience Description
Developer Onboarding New team members What is SyftHub, codebase tour, key concepts
Local Setup All developers Clone to running in 5 minutes
Glossary Everyone Definitions of all SyftHub domain terms

Architecture

Doc Description
Architecture Overview C4 diagrams, service map, token architecture, data flows
Backend FastAPI service — auth, registry, IdP, health monitor
Frontend React 19 SPA — routes, state management, auth flow
Aggregator Stateless RAG service — orchestration, retrieval, streaming
MCP Server OAuth 2.1 + Model Context Protocol for AI assistants

API Reference

Doc Base URL Endpoints
Backend API /api/v1 89 endpoints — auth, users, endpoints, orgs, IdP, NATS, accounting
Aggregator API /aggregator/api/v1 RAG chat + streaming (SSE)
MCP API /mcp OAuth 2.1 flow + MCP tools

OpenAPI (dev): http://localhost:8080/docs


Explanation (Concepts)

Doc Topic
Authentication Dual-token architecture (HS256 hub + RS256 satellite), JWKS, PATs
PKI Workflow Identity Provider, JWKS verification, MCP OAuth flow
RAG Architecture Aggregator pipeline — retrieval, reranking, prompt construction, streaming

How-To Guides

Doc Audience
Publishing Endpoints ML engineers, data scientists
Python SDK 2.x Python developers: search, pre-flight, wallets
Python SDK (legacy) Python developers still on the 0.3 release: endpoint management, chat

Runbooks (Operations)

Doc Use When
Deployment Deploying to dev or production
Rollback Rolling back a bad deployment
Incident Response Triaging production incidents

SDKs

SDK Package Path Install
Python syfthub-sdk (import syfthub) sdk/python/ pip install --pre syfthub-sdk (2.x pre-release; syfthub-sdk<2 for the 0.x client)

The TypeScript SDK, the Go SDK and the syft CLI are retired; their last state is on the legacy-sdks branch. The TypeScript client continues as the frontend's internal API client in components/frontend/src/lib/sdk.


Quick Reference

Dev Commands

make dev      # Start all services
make stop     # Stop all services
make logs     # View container logs
make test     # Run all tests
make check    # Lint + type check

Services (dev)

Service URL
App http://localhost:8080
API Docs http://localhost:8080/docs
Backend http://localhost:8080/api/v1
Aggregator http://localhost:8080/aggregator/api/v1
MCP http://localhost:8080/mcp
PostgreSQL localhost:5432
Redis localhost:6379
Meilisearch localhost:7700

Token Quick Reference

Token Algorithm Lifetime Get via
Hub access HS256 30 min POST /api/v1/auth/login
Refresh Opaque 7 days POST /api/v1/auth/login
Satellite RS256 60 s GET /api/v1/token?aud={user}
PAT Opaque Configurable POST /api/v1/auth/tokens
MCP RS256 1 hr MCP OAuth flow