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 prompts 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 request volume, provider calls, cache activity, coalescing, expirations, and evictions |
Core capabilities:
- independent embedding and generation providers;
- memory or persistent PostgreSQL + pgvector storage;
- TTL, LRU eviction, namespaces, private requests, and read/write policies;
- request coalescing for identical concurrent misses;
- optional typo-aware prompt normalization;
- 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.
Install Git and Docker Desktop, or Docker Engine with Compose.
Linux or macOS:
git clone https://github.com/Dendroculus/semantix.git
cd semantix
cp backend/.env.example backend/.envWindows PowerShell:
git clone https://github.com/Dendroculus/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 |
| 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/
├── 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, 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 |
| 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.