Commercial documentation

Commercial section · 01 / 03

Perché AYXZA Relay

Adding AI to a product is no longer "calling an API". It means juggling five vendors, containing costs, guaranteeing uptime and protecting data. AYXZA Relay solves all of this with a single library.

The problem Without a gateway

✗Duplicated code for each provider (OpenAI, Anthropic, Gemini…)
✗Technical lock-in: changing model = rewriting the integration
✗Costs out of control, no per-tenant visibility
✗One provider down = service down
✗Sensitive data sent to the cloud, no on-prem option
✗RAG / knowledge base built from scratch every time

The solution With AYXZA Relay

+API unica: forge.chat()Single API: forge.chat() works with any model
+Provider switch via config, zero refactoring
+Cost tracking per call, tenant, model — exportable
+Automatic provider failover in milliseconds
+Local Ollama for sensitive data, zero external network
+Built-in Knowledge Base module with pgvector

Cost comparison · smart routing

AYXZA Relay routes each request to the cheapest model that can handle the task. Cost per 1M tokens, indicative public 2026 values.

Input Output

With automatic routing to "small" models for simple tasks and "frontier" only where needed, average cost per request typically drops 60–80%.

Typical use cases

01

Multi-tenant SaaS

Per-customer cost tracking, per-plan limits, different models per tier. Out of the box.

02

On-premise enterprise

Local Ollama for confidential data, optional cloud fallback for non-sensitive tasks.

03

Corporate knowledge base

RAG over internal documents with pgvector, auto re-indexing, per-tenant isolation.

04

Agents & chains

Multi-step orchestration, native structured output (Gemini, OpenAI) and multimodal attachments (PDF, images) on prompts.

05

Provider migration

Switch model with one config line. A/B test across providers without touching code.

06

High availability

Transparent failover: if OpenAI is down, requests reach Anthropic in <100ms.

Economic impact

Conservative estimate on a SaaS product with 10,000 AI calls/day.

Development time saved

~3 months

5 providers integration, tracking, fallback, RAG

API cost reduction

60–80%

Adaptive model-size routing + cache

AI features uptime

99,95%

With multi-provider failover configured

Technical section · 02 / 03

Architecture

Pure Python library, stateless where possible, with persistence on PostgreSQL + pgvector. No external service dependency beyond the LLM providers themselves.

Layered architecture

From the client application to providers, through the core gateway.

flowchart TB subgraph CLIENT["CLIENT APPLICATIONS"] A1["Web App"] A2["Backend API"] A3["CLI / Scripts"] end subgraph FORGE["AYXZA Relay · Gateway Library"] GW["Unified API
forge.chat · forge.embed · forge.rag"] subgraph CORE["Core Services"] R["Router
model selection"] C["Cache
semantic + exact"] T["Tracking
cost · tenant · model"] F["Fallback
provider failover"] K["Knowledge Base
RAG + pgvector"] end GW --> R R --> C C --> T T --> F GW -.-> K end subgraph PROV["LLM PROVIDERS"] P1["OpenAI"] P2["Anthropic"] P3["Google Gemini"] P4["Google Vertex"] P5["Ollama local"] end DB[("PostgreSQL
+ pgvector")] CLIENT --> GW F --> P1 F --> P2 F --> P3 F --> P4 F --> P5 T --> DB K --> DB

Request flow with fallback

Primary provider unavailable, automatic failover to secondary.

sequenceDiagram autonumber participant App as Client App participant Forge as AYXZA Relay participant Cache as Cache Layer participant P1 as OpenAI primary participant P2 as Anthropic fallback participant DB as PostgreSQL App->>Forge: forge.chat(prompt, model="auto") Forge->>Cache: lookup(prompt_hash) Cache-->>Forge: miss Forge->>P1: POST /v1/chat/completions P1-->>Forge: 503 Service Unavailable Note over Forge: Fallback trigger < 100ms Forge->>P2: POST /v1/messages P2-->>Forge: 200 OK + tokens Forge->>Cache: store(prompt_hash, response) Forge->>DB: log(tenant, model, cost, latency) Forge-->>App: response (transparent)

RAG · Knowledge Base pipeline

Ingestion → chunking → embedding → retrieval → generation.

flowchart LR D["Documents
PDF · MD · HTML"] S["Source Registry
staleness tracking"] CH["Chunker
shared utility"] EM["Embedder
text-embedding-004
768-dim"] VS[("pgvector
HNSW index")] Q["User query"] QE["Query embedding"] RT["Retrieval
global + tenant chunks"] GEN["LLM Generation
any provider"] D --> S --> CH --> EM --> VS Q --> QE --> RT VS -.-> RT RT --> GEN

API in action

A handful of lines for chat, automatic fallback, tracking and RAG.

# 1. Inizializzazione — provider configurati una volta sola
from forge_ai import Forge

forge = Forge(
    providers=["openai", "anthropic", "gemini", "ollama"],
    fallback_chain=["openai", "anthropic"],
    tracking=True,
    tenant_id="acme-corp",
)

# 2. Chat — il router sceglie il modello migliore per il task
response = forge.chat(
    prompt="Riassumi questo contratto in 3 punti",
    model="auto",           # o "claude-sonnet-4-5", "gpt-4o", "llama3.1:70b"
    max_tokens=500,
)
print(response.text, response.cost_usd, response.provider_used)

# 3. Output strutturato nativo (Gemini / OpenAI)
from pydantic import BaseModel
class Invoice(BaseModel):
    total: float
    vat: float
    items: list[str]

invoice = forge.chat(
    prompt="Estrai i dati da questa fattura...",
    output_schema=Invoice,
).parsed

# 4. RAG — knowledge base con isolamento per tenant
forge.kb.add_source(name="company-policies", files=["./docs/*.pdf"])
answer = forge.rag(
    query="Qual è la policy sui rimborsi spese?",
    sources=["company-policies"],
)

# 5. Locale — stesso codice, modello Ollama on-prem
private = forge.chat(prompt="...", model="ollama:llama3.1:70b")

Capability matrix

Capability	OpenAI	Anthropic	Gemini	Vertex	Ollama
Chat completion	●	●	●	●	●
Streaming	●	—	●	—	●
Structured output (native)	●	—	●	●	—
Function calling	●	●	●	●	●
Embeddings	●	—	●	●	●
Vision · multimodal	●	●	●	●	●
On-premise · air-gapped	—	—	—	—	●

Requirements

Python 3.12+
PostgreSQL 14+ with pgvector extension
API keys of chosen providers (optional for Ollama)
Ollama installed locally for on-prem LLMs

Tech stack

SQLAlchemy 2.x async
Pydantic v2 for validation and schemas
Alembic for database migrations
httpx with exponential retry policy
Test suite 900+ tests, E2E coverage

Supported providers · 03 / 03

Provider integrati

All major cloud LLM vendors, plus an OpenAI-compatible adapter reaching cloud engines (Groq, DeepSeek, OpenRouter) and local (Ollama, vLLM) air-gapped deployments.

OA

OpenAI

GPT-4o · GPT-4o-mini · o3

Frontier reasoning, full function calling, native structured output.

AN

Anthropic

Claude Opus · Sonnet · Haiku

Long-context (200K+), excellent for long reasoning and document analysis.

GG

Google Gemini

Gemini 2.x · text-embedding-004

Native multimodal, 768-dim embeddings, great cost/performance ratio.

VX

Google Vertex AI

Enterprise GCP · EU residency

Same Gemini model with enterprise SLA, GCP billing, EU data residency.

OL

Ollama

Llama · Mistral · Qwen · local

100% local execution, zero external network, ideal for sensitive data and GDPR. The same OpenAI-compatible adapter also reaches cloud engines (Groq, DeepSeek, OpenRouter).

++

Custom provider

extensible api

Aggiungere un nuovo provider richiede ~150 righe Python implementando l'interfaccia ProviderAdding a new provider takes ~150 lines of Python implementing the Provider interface.

Contact us

To evaluate an integration, discuss a use case or get a personalized demo on your product.

Contact us →