Semantix is a full-stack semantic-cache laboratory for inspecting cache decisions, measuring provider savings, evaluating similarity thresholds, and comparing replaceable AI and storage providers.
Monitor · Cache Inspector · Evaluations · Runtime Observability
| Workspace | Purpose |
|---|---|
| Monitor | Submit namespace-scoped policy probes and inspect cache hits, misses, latency, matched prompts, and similarity evidence |
| Cache Inspector | Search entries, inspect metadata, delete records, clear namespaces, and manage the threshold |
| Evaluations | Measure precision, recall, false hits, false misses, inspect filtered case evidence, and export reproducible runs |
| Observability | Track process metrics and inspect safe, read-only runtime diagnostics for evaluation reproducibility |
Core capabilities:
- independent embedding and generation providers;
- memory or persistent PostgreSQL + pgvector storage;
- TTL, LRU eviction, namespaces, private requests, and read/write policies;
- role-aware Monitor controls, private trace minimization, and live-hit links to authorized Cache detail;
- request coalescing for identical concurrent misses;
- optional typo-aware prompt normalization;
- global-admin-only runtime diagnostics with safe provider categories, fingerprints, readiness, and evaluation limits;
- token roles and namespace authorization for hardened deployments;
- deterministic mock providers for safe local testing.
- run-local evaluation caches, complete confusion-matrix accounting, and configurable bounded frozen-candidate threshold sweeps;
- versioned session-local JSON evaluation datasets with provider-free preview, strict validation, and no browser persistence;
- optional namespace-authorized PostgreSQL evaluation dataset catalog with explicit save, bounded retention, and no stored run results.
Prompt
│
▼
Normalize matching text
│
▼
Create embedding
│
▼
Search the active namespace and embedding space
│
├── score >= threshold ──► return cached response
│
└── score < threshold ───► call provider ─► store response
Semantix returns a cached response only when the nearest compatible entry meets the active similarity threshold. See Cache policies for the complete rules.
External Python applications can use the independently installable
semantix-client distribution through the public HTTP API.
Python code imports it as semantix_client. It provides typed synchronous and
asynchronous clients without installing or importing Semantix backend internals.
The package is not currently published to PyPI; install it from a built wheel or directly from the repository as described in the full guide.
from semantix_client import SemantixClient
with SemantixClient(base_url="http://localhost:8000") as client:
result = client.query("Explain semantic caching", namespace="default")
print(result.response, result.cache_hit)Install Git and Docker Desktop, or Docker Engine with Compose.
Linux or macOS:
git clone https://github.com/Yoruxyv/semantix.git
cd semantix
cp backend/.env.example backend/.envWindows PowerShell:
git clone https://github.com/Yoruxyv/semantix.git
Set-Location semantix
Copy-Item backend\.env.example backend\.envFor a zero-key persistent setup, use these values in backend/.env:
EMBEDDING_PROVIDER=mock
GENERATION_PROVIDER=mock
MOCK_EMBEDDING_DIMENSIONS=384
CACHE_BACKEND=pgvector
DATABASE_URL=postgresql://semantix:semantix@postgres:5432/semantix
DATABASE_MIGRATION_MODE=auto
EVALUATION_DATASET_STORAGE=postgres
EVALUATION_DATASET_DEFAULT_RETENTION_DAYS=30
AUTH_MODE=disabled
AUTH_PRINCIPALS=[]
TRUSTED_PROXY_CIDRS=[]
MAX_REQUEST_BODY_BYTES=65536These authentication and proxy values are intentionally empty or disabled for trusted local development. Do not use the development configuration for a public deployment.
To use Hugging Face, OpenAI, Anthropic, Gemini, or Ollama, see
Providers. For every environment option, see
Getting started and backend/.env.example.
docker compose -f docker-compose.dev.yml --profile pgvector up --build -dThis single command starts:
- the React frontend with Vite hot reload;
- the FastAPI backend with Uvicorn reload;
- PostgreSQL with pgvector;
- automatic development database migrations.
| Service | Address |
|---|---|
| Frontend | http://localhost:4173 |
| Backend | http://localhost:8000 |
| API documentation | http://localhost:8000/docs |
| Liveness | http://localhost:8000/health |
| Readiness | http://localhost:8000/ready |
| Runtime metrics | http://localhost:8000/api/v1/metrics |
| Runtime diagnostics | http://localhost:8000/api/v1/diagnostics |
| PostgreSQL from the host | 127.0.0.1:5433 |
Useful commands:
docker compose -f docker-compose.dev.yml --profile pgvector ps
docker compose -f docker-compose.dev.yml --profile pgvector logs -f backend
docker compose -f docker-compose.dev.yml --profile pgvector downdown keeps named volumes. Adding --volumes deletes the local PostgreSQL
data.
Embedding and generation providers are selected independently.
| Provider | Embeddings | Generation | Credentials |
|---|---|---|---|
| Hugging Face | Yes | Yes | Required |
| OpenAI | Yes | Yes | Required |
| Anthropic | No | Yes | Required |
| Gemini | Yes | Yes | Required |
| Ollama | Yes | Yes | Not required locally |
| Mock | Yes | Yes | Not required |
Only settings required by the selected capabilities are validated. See Providers for configuration examples and networking notes.
| Mode | Intended use | Main behavior |
|---|---|---|
| Development | One trusted local developer | Hot reload, loopback ports, disabled authentication, automatic migrations |
| Hardened | Shared or public single-instance deployment | Token authentication, namespace roles, internal backend/database networks, external migrations, TLS proxy required |
Create .env.production from .env.production.example only when preparing a
hardened deployment:
docker compose --env-file .env.production -f docker-compose.prod.yml up --build -dDo not start it until every placeholder has been replaced. See Hardened deployment for token generation, trusted proxies, database roles, TLS, and validation.
A local run on July 19, 2026 used the eight-query Quick semantic safety set,
Hugging Face providers, typo normalization, an empty isolated cache, and a
0.92 threshold:
| Provider calls avoided | Average hit | Average miss | Precision / Recall / F1 |
|---|---|---|---|
| 4 of 8 (50%) | 330.3 ms | 3772.7 ms | 1.0 / 1.0 / 1.0 |
This is one dated measurement, not a performance guarantee. See Benchmarking for the dataset, run details, and limitations.
Backend tool caches are centralized under backend/.cache/. Enable the Python
bytecode cache redirect before running backend commands.
From the repository root:
Windows PowerShell:
. .\backend\scripts\windows\enable_cache.ps1Linux or macOS:
source backend/scripts/linux/enable_cache.shWhen already inside backend/:
Windows PowerShell:
. .\scripts\windows\enable_cache.ps1Linux or macOS:
source scripts/linux/enable_cache.shThe leading dot in PowerShell and source in Bash are required so
PYTHONPYCACHEPREFIX remains active in the current terminal. Ruff, mypy, and
pytest use their cache paths from backend/pyproject.toml.
To remove generated caches and editable-install metadata:
.\backend\scripts\windows\clean_artifacts.ps1For Linux or macOS:
bash backend/scripts/linux/clean_artifacts.shPlatform-specific automation lives in windows/ and linux/ directories.
Shared Compose overlays remain beside those directories under ops/ci/.
For example, the development health smoke has matching entry points:
Windows PowerShell:
.\ops\ci\windows\dev-healthcheck-smoke.ps1Linux or macOS:
bash ops/ci/linux/dev-healthcheck-smoke.shThe smoke entry points generate ephemeral database passwords and authentication tokens for each run unless the corresponding environment variables are already set. Credentials are not stored in the scripts.
Repository-wide developer reports are available through paired platform helpers:
.\scripts\windows\get_total_lines.ps1
.\scripts\windows\find_undocumented_files.ps1bash scripts/linux/get_total_lines.sh
bash scripts/linux/find_undocumented_files.shThey inspect Git-tracked and unignored project files, so ignored dependencies, caches, virtual environments, and build output are excluded automatically.
Backend:
cd backend
uv sync --locked --extra dev
uv run --locked pytest
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked mypy app tests scriptsFrontend:
cd frontend
npm ci
npm run lint
npm run imports:check
npm run test
npm run buildSee Development for local toolchains, architecture rules, and contribution steps.
semantix/
├── backend/
├── frontend/
├── sdk/
│ └── python/
├── ops/
│ ├── ci/
│ ├── load-testing/
│ ├── postgres/
│ └── supply-chain/
├── scripts/
│ ├── linux/
│ └── windows/
├── docs/
├── docker-compose.dev.yml
├── docker-compose.prod.yml
└── README.md
The backend and frontend use feature-first ownership. See Architecture for the runtime flow and package boundaries.
- Semantic similarity is probabilistic and must be evaluated for each model and workload.
- Hosted providers may receive prompts and can introduce cost, latency, and external data-handling requirements.
- Runtime metrics, diagnostics, rate limiting, and request coalescing are process-local.
- The hardened stack is a single-instance baseline, not a complete multi-tenant or multi-replica platform.
- Mock providers are for tests, demonstrations, and UI development.
- Evaluation sweeps reuse one measured run; alternate thresholds are projections, not ordered replays or automatic threshold recommendations.
The documentation index groups the full guides by purpose.
| Start here | Use it for |
|---|---|
| Getting started | Local setup, environment files, and Docker workflows |
| Providers | Hosted, local, and mock provider configuration |
| Python SDK | Install and use the typed public HTTP client |
| Architecture | Runtime flow, feature ownership, and package boundaries |
| Hardened deployment | Authentication, TLS, database roles, and production validation |
Made with ❤️ by:
 Hans |
 Louis |
Licensed under the MIT License.