Changelog

All notable changes to this project will be documented in this file.

[v2.0.0] - 2025-12-09

Rebrand: Project renamed from Meridian to Fabra (context infrastructure for AI applications).
- Package renamed from meridian-oss to fabra on PyPI.
- CLI command changed from meridian to fabra.
- All imports changed from from meridian to from fabra.
Breaking Changes:
- Environment variables renamed: MERIDIAN_* → FABRA_*.
- Internal metric names renamed: meridian_* → fabra_*.
- Config file renamed: meridian.toml → fabra.toml.
Migration: Users of meridian-oss should update imports and environment variables.

Next.js UI Migration: Replaced Streamlit UI with modern Next.js 14 application.
- Built with React, TypeScript, and Tailwind CSS.
- App Router architecture for optimal performance.
- Dark theme with professional design.
FastAPI Backend: New dedicated UI backend server.
- GET /api/store - List features, retrievers, and contexts.
- POST /api/features/get - Retrieve feature values.
- POST /api/context/assemble - Assemble context with parameters.
Feature Explorer: Browse and search all registered features.
- View feature metadata, types, and dependencies.
- Real-time feature value retrieval with entity inputs.
Context Assembly UI: Interactive context testing.
- Parameter input forms with defaults.
- Rich result display with token counts and costs.
- Raw JSON viewer for debugging.
E2E Testing: Playwright test suite with 18 comprehensive tests.

Freshness SLA Parameter: Configure maximum age for features used in context assembly.
- @context(store, freshness_sla="5m") - Require features to be less than 5 minutes old.
- Supports multiple formats: "30s", "5m", "1h", "1d", "500ms".
Degraded Mode: Graceful handling when features exceed SLA threshold.
- Context assembly succeeds but freshness_status becomes "degraded".
- freshness_violations list provides details on stale features.
- Structured logging warns when SLA is breached.
Strict Mode: Optional hard failure on SLA breach.
- @context(store, freshness_sla="30s", freshness_strict=True) - Raise FreshnessSLAError on violation.
- Exception includes full violation details for debugging.
Prometheus Metrics:
- fabra_context_freshness_status_total{status="guaranteed|degraded"} - Track freshness status.
- fabra_context_freshness_violations_total{feature="..."} - Track violations by feature.
- fabra_context_stalest_feature_seconds - Histogram of stalest feature ages.

Added src/fabra/utils/time.py with parse_duration_to_ms() and format_ms_to_human() utilities.
Added FreshnessSLAError exception with structured violation data.
Context meta now includes freshness_violations and freshness_sla_ms fields.
Added is_fresh property to Context class for easy checking.

Context Lineage Tracking: Automatically track exactly what data was used in every context assembly.
- FeatureLineage records which features were retrieved, their values, timestamps, and freshness.
- RetrieverLineage records which retrievers were called, queries, result counts, and latencies.
- ContextLineage provides full assembly statistics including items dropped, token usage, and cost.
UUIDv7 Context Identifiers: Time-sortable unique IDs for efficient querying and debugging.
Context Replay API: Retrieve any historical context by ID for debugging and compliance.
- store.get_context_at(context_id) - Get full context with lineage.
- store.list_contexts(start, end, limit) - List contexts in a time range.
REST API Endpoints:
- GET /v1/contexts - List contexts with time filtering.
- GET /v1/context/{id} - Retrieve full context by ID.
- GET /v1/context/{id}/lineage - Get just the lineage data.
CLI Commands:
- fabra context show - Display context details.
- fabra context list - List recent contexts.
- fabra context export - Export context for audit (JSON/YAML).

AssemblyTracker uses contextvars for clean lineage tracking without API changes.
Graceful degradation: context logging failures don't fail assembly.
Context table auto-created in both DuckDB and Postgres offline stores.

Context Store: Full RAG infrastructure for LLM applications.
- @retriever decorator for semantic search with automatic caching.
- @context decorator for composing context with token budgets.
- Priority-based truncation with ContextItem(priority=N, required=True/False).
Vector Search:
- pgvector integration for Postgres with cosine similarity.
- Automatic document chunking via tiktoken.
- Multiple embedding providers (OpenAI, Cohere).
Event-Driven Architecture:
- AxiomEvent model for structured events.
- RedisEventBus for publishing to Redis Streams.
- AxiomWorker for consuming events and triggering feature updates.
- Trigger-based features with @feature(trigger="event_name").
DAG Resolution:
- Implicit wiring via {feature_name} template syntax.
- DependencyResolver for automatic dependency graph construction.
Observability:
- ContextTrace model for debugging context assembly.
- /context/{id}/explain API endpoint.
- ContextMetrics for Prometheus integration.
Time Travel:
- get_historical_features() for point-in-time queries.
- Debug production issues by querying past state.
Diagnostics:
- fabra doctor CLI command for environment diagnostics.
- Checks Redis, Postgres, and environment variable configuration.

Production Stack (FABRA_ENV=production): full support for running in production with Postgres (Async) and Redis.
Point-in-Time Correctness:
- Development: Uses DuckDB ASOF JOIN logic for zero leakage.
- Production: Uses Postgres LATERAL JOIN logic for zero leakage.
Async Offline Store: PostgresOfflineStore now uses asyncpg for high-throughput I/O.
Hybrid Feature Fixes: Correctly merges Python (on-the-fly) and SQL (batch) features in retrieval.

Fixed AttributeError in prod_app.py regarding timedelta.
Fixed data loss issue in PostgresOfflineStore where Python features were dropped during hybrid retrieval.
Fixed type casting issues in RedisOnlineStore.

Added Feast Comparison page.
Added FAQ page.
Added Use Case guides:
- Churn Prediction (PIT Focus)
- Real-Time Recommendations (Hybrid Focus)
Added Architecture Diagram to README.