add preview disclaimers

Author: krisztianfekete

DEVELOPMENT.md

@@ -29,6 +29,11 @@ Standard development uses `dev-backend` + `dev-frontend` in separate terminals.
 
 ### Postgres backend (optional, for `/api/runs`)
 
+> **Preview.** The schema, the CLI surface, and `/api/runs` shape are still
+> stabilizing. Recreate the agentevals schema between minor version upgrades
+> until further notice; do not depend on persisted data surviving a
+> `git pull` of agentevals itself.
+
 The default in-memory backend keeps `make dev-backend` zero-config. To exercise the async run pipeline locally, bring up a Postgres alongside the app:
 
 ```bash

README.md

@@ -288,6 +288,13 @@ See the [Kubernetes example](examples/kubernetes/README.md) for an end-to-end wa
 
 #### Postgres backend (`/api/runs`)
 
+> **Preview.** Persistent run history backed by Postgres is under active
+> development. The `storage.*` and `database.postgres.*` chart values, the
+> `/api/runs` HTTP surface, and the database schema may change incompatibly
+> in upcoming releases. Operators evaluating this feature should plan to
+> recreate the agentevals schema when upgrading between minor versions.
+> Default in-memory mode is unaffected.
+
 By default the chart deploys agentevals with an in-memory backend; runs and results are not persisted. To enable the async `POST /api/runs` pipeline with durable Postgres-backed state:
 
 ```bash

charts/agentevals/templates/NOTES.txt

@@ -11,3 +11,11 @@ Get the Service URL:
   kubectl --namespace {{ include "agentevals.namespace" . }} port-forward $POD_NAME {{ .Values.service.http.port }}:{{ .Values.service.http.port }}
 
 Health check: GET http://<pod-ip>:{{ .Values.service.http.containerPort }}/api/health
+
+{{- if eq .Values.storage.backend "postgres" }}
+
+NOTE: Postgres-backed storage is a preview feature. The storage.* and
+database.postgres.* values, the /api/runs HTTP surface, and the database
+schema may change incompatibly in upcoming releases. Recreate the
+agentevals schema when upgrading between minor versions.
+{{- end }}

charts/agentevals/values.yaml

@@ -160,13 +160,19 @@ env: []
 envFrom: []
 
 # ==============================================================================
-# STORAGE
+# STORAGE  (preview feature)
+#
+# Persistent run history backed by Postgres is under active development.
+# storage.* and database.postgres.* keys, and the underlying schema, may
+# change incompatibly in upcoming releases. Treat persisted runs and
+# results as ephemeral; recreate the agentevals schema when upgrading
+# between minor versions. Default in-memory backend is unaffected.
 # ==============================================================================
 
 storage:
   # -- Storage backend. "memory" (default) keeps the developer experience
   # zero-config: nothing persisted, restarts lose in-flight state. "postgres"
-  # enables /api/runs and persists runs + results in Postgres.
+  # enables /api/runs and persists runs + results in Postgres (preview).
   backend: memory
 
 # ==============================================================================

src/agentevals/api/app.py

@@ -109,6 +109,18 @@ def create_app(
         version=__version__,
         description="REST API for evaluating agent traces using ADK's scoring framework",
         lifespan=_build_lifespan(),
+        openapi_tags=[
+            {
+                "name": "runs",
+                "description": (
+                    "**Preview.** Async run pipeline backed by Postgres. The shape of "
+                    "submission, responses, and persisted run / result data may change "
+                    "incompatibly in upcoming releases. Operators evaluating this "
+                    "surface should plan to recreate persisted data when upgrading "
+                    "agentevals between minor versions."
+                ),
+            },
+        ],
     )
 
     app.add_middleware(

src/agentevals/api/runs_routes.py

@@ -28,7 +28,18 @@
 
 logger = logging.getLogger(__name__)
 
-runs_router = APIRouter(tags=["runs"])
+runs_router = APIRouter(
+    tags=["runs"],
+    responses={
+        503: {
+            "description": (
+                "Storage backend is not configured. Set "
+                "AGENTEVALS_STORAGE_BACKEND=postgres (with AGENTEVALS_DATABASE_URL) "
+                "to enable run history."
+            )
+        },
+    },
+)
 
 
 class RunRequest(CamelModel):

src/agentevals/cli.py

@@ -767,6 +767,10 @@ def _migrator_or_die() -> "object":
 @click.option("--dry-run", is_flag=True, help="Print which migrations would apply without executing.")
 def migrate_up(dry_run: bool) -> None:
     """Apply all pending migrations."""
+    click.echo(
+        "note: agentevals migrate is a preview feature. Schema may change incompatibly between minor releases.",
+        err=True,
+    )
     migrator = _migrator_or_die()
     try:
         applied = asyncio.run(migrator.up(dry_run=dry_run))