Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(observer): support JSON status format (#5316)
Jiahui Zhou34326306c139
diff --git a/openviking/server/routers/observer.py b/openviking/server/routers/observer.pyindex f88a0804c..31d40cf11 100644--- a/openviking/server/routers/observer.py+++ b/openviking/server/routers/observer.py@@ -10,7 +10,9 @@ Mirrors SDK's client.observer API:- /api/v1/observer/system - System overall status"""-from fastapi import APIRouter, Depends+from typing import Literal++from fastapi import APIRouter, Depends, Queryfrom openviking.server.auth import get_request_contextfrom openviking.server.dependencies import get_service@@ -45,68 +47,89 @@ def _system_to_dict(status: SystemStatus) -> dict:@router.get("/queue")async def observer_queue(_ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get queue system status."""service = get_service()- component = service.debug.observer.queue+ component = service.debug.observer.get_queue_status(format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/vikingdb")async def observer_vikingdb(ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get VikingDB status."""service = get_service()- component = service.debug.observer.vikingdb(ctx=ctx)+ component = service.debug.observer.get_vikingdb_status(ctx=ctx, format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/models")async def observer_models(_ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get models status (VLM, Embedding, Rerank)."""service = get_service()- component = service.debug.observer.models+ component = service.debug.observer.get_models_status(format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/lock")async def observer_lock(_ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get lock system status."""service = get_service()- component = service.debug.observer.lock+ component = service.debug.observer.get_lock_status(format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/retrieval")async def observer_retrieval(_ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get retrieval quality metrics."""service = get_service()- component = service.debug.observer.retrieval+ component = service.debug.observer.get_retrieval_status(format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/filesystem")async def observer_filesystem(_ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get filesystem operation metrics."""service = get_service()- component = service.debug.observer.filesystem+ component = service.debug.observer.get_filesystem_status(format=format)return Response(status="ok", result=_component_to_dict(component))@router.get("/system")async def observer_system(ctx: RequestContext = Depends(get_request_context),+ format: Literal["table", "json"] = Query(+ "table", description="Observer status representation format"+ ),):"""Get system overall status (includes all components)."""service = get_service()- status = service.debug.observer.system(ctx=ctx)+ status = service.debug.observer.system(ctx=ctx, format=format)return Response(status="ok", result=_system_to_dict(status))diff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.pyindex 1e792d2d3..94ffa1c67 100644--- a/openviking/service/debug_service.py+++ b/openviking/service/debug_service.py@@ -25,6 +25,60 @@ from openviking_cli.utils.logger import get_loggerlogger = get_logger(__name__)+def _queue_not_initialized_status(format: str) -> Any:+ if format == "json":+ return {+ "queues": [],+ "summary": {+ "pending": 0,+ "in_progress": 0,+ "processed": 0,+ "requeued": 0,+ "errors": 0,+ "total": 0,+ },+ "error": "Not initialized",+ }+ return "Not initialized"+++def _vikingdb_not_initialized_status(format: str) -> Any:+ if format == "json":+ return {+ "collections": [],+ "summary": {+ "index_count": 0,+ "vector_count": 0,+ "collection_count": 0,+ },+ "error": "Not initialized",+ }+ return "Not initialized"+++def _models_not_initialized_status(format: str) -> Any:+ if format == "json":+ return {+ "vlm": [],+ "embedding": [],+ "rerank": [],+ "error": "Not initialized",+ }+ return "Not initialized"+++def _lock_not_initialized_status(format: str) -> Any:+ if format == "json":+ return {+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflict_count": 0,+ "error": "Not initialized",+ }+ return "Not initialized"++@dataclassclass ComponentStatus:"""Component status."""@@ -32,7 +86,7 @@ class ComponentStatus:name: stris_healthy: boolhas_errors: bool- status: str+ status: Anydef __str__(self) -> str:health = "healthy" if self.is_healthy else "unhealthy"@@ -89,8 +143,7 @@ class ObserverService:"""Check if both vikingdb and config dependencies are set."""return self._vikingdb is not None and self._config is not None- @property- def queue(self) -> ComponentStatus:+ def get_queue_status(self, *, format: str = "table") -> ComponentStatus:"""Get queue status."""try:qm = get_queue_manager()@@ -99,57 +152,97 @@ class ObserverService:name="queue",is_healthy=False,has_errors=True,- status="Not initialized",+ status=_queue_not_initialized_status(format),)observer = QueueObserver(qm)+ try:+ status = observer.get_status_json() if format == "json" else observer.get_status_table()+ is_healthy = observer.is_healthy()+ has_errors = observer.has_errors()+ except Exception as exc:+ logger.warning("Queue observer status unavailable: %s", exc)+ if format == "json":+ status = {+ "queues": [],+ "summary": {+ "pending": 0,+ "in_progress": 0,+ "processed": 0,+ "requeued": 0,+ "errors": 0,+ "total": 0,+ },+ "error": str(exc),+ }+ else:+ status = f"Status unavailable: {exc}"+ is_healthy = False+ has_errors = Truereturn ComponentStatus(name="queue",- is_healthy=observer.is_healthy(),- has_errors=observer.has_errors(),- status=observer.get_status_table(),+ is_healthy=is_healthy,+ has_errors=has_errors,+ status=status,)- def vikingdb(self, ctx: Optional[RequestContext] = None) -> ComponentStatus:+ @property+ def queue(self) -> ComponentStatus:+ """Get queue status."""+ return self.get_queue_status()++ def get_vikingdb_status(+ self, ctx: Optional[RequestContext] = None, *, format: str = "table"+ ) -> ComponentStatus:"""Get VikingDB status."""if self._vikingdb is None:return ComponentStatus(name="vikingdb",is_healthy=False,has_errors=True,- status="Not initialized",+ status=_vikingdb_not_initialized_status(format),)observer = VikingDBObserver(self._vikingdb)return ComponentStatus(name="vikingdb",is_healthy=observer.is_healthy(),has_errors=observer.has_errors(),- status=observer.get_status_table(ctx=ctx),+ status=observer.get_status_json(ctx=ctx)+ if format == "json"+ else observer.get_status_table(ctx=ctx),)+ def vikingdb(self, ctx: Optional[RequestContext] = None) -> ComponentStatus:+ """Get VikingDB status."""+ return self.get_vikingdb_status(ctx=ctx)+@propertydef models(self) -> ComponentStatus:"""Get Models status (VLM, Embedding, Rerank)."""+ return self.get_models_status()++ def get_models_status(self, *, format: str = "table") -> ComponentStatus:+ """Get Models status (VLM, Embedding, Rerank) with a specific status format."""if self._config is None:return ComponentStatus(name="models",is_healthy=False,has_errors=True,- status="Not initialized",+ status=_models_not_initialized_status(format),)vlm_instance = self._config.vlm.get_vlm_instance()embedding_instance = Nonererank_instance = None+ embedding_config = getattr(self._config, "embedding", None)+ rerank_config = getattr(self._config, "rerank", None)- # Get embedding instance if available- if self._config.embedding:- embedding_instance = self._config.embedding.get_embedder()+ if embedding_config:+ embedding_instance = embedding_config.get_embedder()- # Get rerank instance if available- if self._config.rerank and self._config.rerank.is_available():+ if rerank_config and rerank_config.is_available():from openviking.models.rerank import RerankClient- rerank_instance = RerankClient.from_config(self._config.rerank)+ rerank_instance = RerankClient.from_config(rerank_config)observer = ModelsObserver(vlm_instance=vlm_instance,@@ -160,7 +253,7 @@ class ObserverService:name="models",is_healthy=observer.is_healthy(),has_errors=observer.has_errors(),- status=observer.get_status_table(),+ status=observer.get_status_json() if format == "json" else observer.get_status_table(),)@property@@ -174,7 +267,7 @@ class ObserverService:name="lock",is_healthy=False,has_errors=True,- status="Not initialized",+ status=_lock_not_initialized_status(format),)active = snapshot.get("active_locks", 0)waiting = snapshot.get("waiting_locks", 0)@@ -194,6 +287,45 @@ class ObserverService:status="\n".join(lines),)+ def get_lock_status(self, *, format: str = "table") -> ComponentStatus:+ """Get lock system status via pathlock_observe snapshot."""+ try:+ viking_fs = get_viking_fs()+ snapshot = run_async(viking_fs._async_agfs.pathlock_observe())+ except Exception:+ return ComponentStatus(+ name="lock",+ is_healthy=False,+ has_errors=True,+ status=_lock_not_initialized_status(format),+ )+ active = snapshot.get("active_locks", 0)+ waiting = snapshot.get("waiting_locks", 0)+ stale = snapshot.get("stale_locks_removed", 0)+ conflicts = snapshot.get("conflicts", [])+ if format == "json":+ status: Any = {+ "active_locks": active,+ "waiting_locks": waiting,+ "stale_locks_removed": stale,+ "conflict_count": len(conflicts),+ }+ else:+ status = "\n".join(+ [+ f"Active locks: {active}",+ f"Waiting locks: {waiting}",+ f"Stale locks removed: {stale}",+ f"Conflicts: {len(conflicts)}",+ ]+ )+ return ComponentStatus(+ name="lock",+ is_healthy=True,+ has_errors=False,+ status=status,+ )+@propertydef retrieval(self) -> ComponentStatus:"""Get retrieval quality status."""@@ -205,6 +337,16 @@ class ObserverService:status=observer.get_status_table(),)+ def get_retrieval_status(self, *, format: str = "table") -> ComponentStatus:+ """Get retrieval quality status."""+ observer = RetrievalObserver()+ return ComponentStatus(+ name="retrieval",+ is_healthy=observer.is_healthy(),+ has_errors=observer.has_errors(),+ status=observer.get_status_json() if format == "json" else observer.get_status_table(),+ )+@propertydef filesystem(self) -> ComponentStatus:"""Get filesystem operation status."""@@ -216,6 +358,16 @@ class ObserverService:status=observer.get_status_table(),)+ def get_filesystem_status(self, *, format: str = "table") -> ComponentStatus:+ """Get filesystem operation status."""+ observer = FilesystemObserver()+ return ComponentStatus(+ name="filesystem",+ is_healthy=observer.is_healthy(),+ has_errors=observer.has_errors(),+ status=observer.get_status_json() if format == "json" else observer.get_status_table(),+ )+async def get_filesystem_stats(self, mount_path: Optional[str] = None) -> dict:"""Get filesystem statistics from RAGFS.@@ -240,15 +392,15 @@ class ObserverService:logger.error(f"Error getting filesystem stats: {e}")return {}- def system(self, ctx: Optional[RequestContext] = None) -> SystemStatus:+ def system(self, ctx: Optional[RequestContext] = None, *, format: str = "table") -> SystemStatus:"""Get system overall status."""components = {- "queue": self.queue,- "vikingdb": self.vikingdb(ctx=ctx),- "models": self.models,- "lock": self.lock,- "retrieval": self.retrieval,- "filesystem": self.filesystem,+ "queue": self.get_queue_status(format=format),+ "vikingdb": self.get_vikingdb_status(ctx=ctx, format=format),+ "models": self.get_models_status(format=format),+ "lock": self.get_lock_status(format=format),+ "retrieval": self.get_retrieval_status(format=format),+ "filesystem": self.get_filesystem_status(format=format),}errors = [f"{c.name} has errors" for c in components.values() if c.has_errors]return SystemStatus(diff --git a/openviking/storage/observers/base_observer.py b/openviking/storage/observers/base_observer.pyindex 57a06c014..03034c85e 100644--- a/openviking/storage/observers/base_observer.py+++ b/openviking/storage/observers/base_observer.py@@ -7,6 +7,7 @@ Defines the common interface that all observers must implement."""import abc+from typing import Anyclass BaseObserver(abc.ABC):@@ -27,6 +28,10 @@ class BaseObserver(abc.ABC):"""pass+ def get_status_json(self) -> Any | None:+ """Return structured status information when available."""+ return None+@abc.abstractmethoddef is_healthy(self) -> bool:"""diff --git a/openviking/storage/observers/filesystem_observer.py b/openviking/storage/observers/filesystem_observer.pyindex a7079f08f..68636dd81 100644--- a/openviking/storage/observers/filesystem_observer.py+++ b/openviking/storage/observers/filesystem_observer.py@@ -140,6 +140,15 @@ class FilesystemObserver(BaseObserver):logger.error(f"Error getting filesystem stats: {e}")return f"Error retrieving filesystem statistics: {e}"+ def get_status_json(self) -> dict:+ """Return filesystem statistics as structured JSON."""+ try:+ observer_service = self._get_collector()+ return run_async(observer_service.get_filesystem_stats(self.mount_path))+ except Exception as e:+ logger.error(f"Error getting filesystem stats: {e}")+ return {"error": str(e), "mounts": []}+def __str__(self) -> str:return self.get_status_table()diff --git a/openviking/storage/observers/models_observer.py b/openviking/storage/observers/models_observer.pyindex 4786073f6..1c0bd4db7 100644--- a/openviking/storage/observers/models_observer.py+++ b/openviking/storage/observers/models_observer.py@@ -48,6 +48,37 @@ class ModelsObserver(BaseObserver):"""return self._format_status_as_table()+ def get_status_json(self) -> dict:+ """Return model usage data as structured JSON."""+ vlm = []+ embedding = []+ rerank = []++ if self._vlm_instance:+ try:+ vlm = self._get_vlm_usage() or self._get_configured_vlm() or []+ except Exception as e:+ logger.warning(f"Error getting VLM usage: {e}")+ vlm = self._get_configured_vlm() or []++ if self._embedding_instance:+ try:+ embedding = self._get_embedding_usage() or []+ except Exception as e:+ logger.warning(f"Error getting Embedding usage: {e}")++ if self._rerank_instance:+ try:+ rerank = self._get_rerank_usage() or []+ except Exception as e:+ logger.warning(f"Error getting Rerank usage: {e}")++ return {+ "vlm": vlm,+ "embedding": embedding,+ "rerank": rerank,+ }+def _format_status_as_table(self) -> str:"""Format token usage status as a table using tabulate.diff --git a/openviking/storage/observers/queue_observer.py b/openviking/storage/observers/queue_observer.pyindex 946e6696f..f07923c20 100644--- a/openviking/storage/observers/queue_observer.py+++ b/openviking/storage/observers/queue_observer.py@@ -32,9 +32,64 @@ class QueueObserver(BaseObserver):tree_stats = self._get_semantic_tree_stats()return self._format_status_as_table(statuses, tree_stats)+ async def get_status_json_async(self) -> dict:+ statuses = await self._queue_manager.check_status()+ tree_stats = self._get_semantic_tree_stats()+ queues = []+ total_pending = 0+ total_in_progress = 0+ total_processed = 0+ total_requeues = 0+ total_errors = 0++ for queue_name, status in statuses.items():+ total = status.pending + status.in_progress + status.processed+ queues.append(+ {+ "queue": queue_name,+ "pending": status.pending,+ "in_progress": status.in_progress,+ "processed": status.processed,+ "requeued": status.requeue_count,+ "errors": status.error_count,+ "total": total,+ }+ )+ total_pending += status.pending+ total_in_progress += status.in_progress+ total_processed += status.processed+ total_requeues += status.requeue_count+ total_errors += status.error_count++ semantic = {+ "queue": "Semantic-Nodes",+ "pending": getattr(tree_stats, "pending_nodes", 0) if tree_stats else 0,+ "in_progress": getattr(tree_stats, "in_progress_nodes", 0) if tree_stats else 0,+ "processed": getattr(tree_stats, "done_nodes", 0) if tree_stats else 0,+ "requeued": 0,+ "errors": 0,+ "total": getattr(tree_stats, "total_nodes", 0) if tree_stats else 0,+ }+ queues.append(semantic)++ return {+ "queues": queues,+ "summary": {+ "pending": total_pending,+ "in_progress": total_in_progress,+ "processed": total_processed,+ "requeued": total_requeues,+ "errors": total_errors,+ "total": total_pending + total_in_progress + total_processed,+ },+ }+def get_status_table(self) -> str:return run_async(self.get_status_table_async())+ def get_status_json(self) -> dict:+ return run_async(self.get_status_json_async())+def __str__(self) -> str:return self.get_status_table()diff --git a/openviking/storage/observers/retrieval_observer.py b/openviking/storage/observers/retrieval_observer.pyindex 61be220c0..c139079a8 100644--- a/openviking/storage/observers/retrieval_observer.py+++ b/openviking/storage/observers/retrieval_observer.py@@ -31,6 +31,11 @@ class RetrievalObserver(BaseObserver):"""Format retrieval statistics as a string table."""return self._format_status_as_table()+ def get_status_json(self) -> dict:+ """Return retrieval statistics as structured JSON."""+ stats = self._get_collector().snapshot()+ return stats.to_dict()+def _format_status_as_table(self) -> str:"""Format retrieval stats as a table using tabulate."""from tabulate import tabulatediff --git a/openviking/storage/observers/vikingdb_observer.py b/openviking/storage/observers/vikingdb_observer.pyindex a6c836c36..d3a72b4a6 100644--- a/openviking/storage/observers/vikingdb_observer.py+++ b/openviking/storage/observers/vikingdb_observer.py@@ -39,9 +39,61 @@ class VikingDBObserver(BaseObserver):)return self._format_status_as_table(statuses)+ async def get_status_json_async(self, ctx: Optional[RequestContext] = None) -> dict:+ if not self._vikingdb_manager:+ return {+ "collections": [],+ "summary": {+ "index_count": 0,+ "vector_count": 0,+ "collection_count": 0,+ },+ }++ if not await self._vikingdb_manager.collection_exists():+ return {+ "collections": [],+ "summary": {+ "index_count": 0,+ "vector_count": 0,+ "collection_count": 0,+ },+ }++ statuses = await self._get_collection_statuses(+ [self._vikingdb_manager.collection_name], ctx=ctx+ )+ collections = []+ total_indexes = 0+ total_vectors = 0+ for name, status in statuses.items():+ item = {+ "collection": name,+ "index_count": status.get("index_count", 0),+ "vector_count": status.get("vector_count", 0),+ "ok": not bool(status.get("error")),+ }+ if status.get("error"):+ item["error"] = status["error"]+ collections.append(item)+ total_indexes += item["index_count"]+ total_vectors += item["vector_count"]++ return {+ "collections": collections,+ "summary": {+ "index_count": total_indexes,+ "vector_count": total_vectors,+ "collection_count": len(collections),+ },+ }+def get_status_table(self, ctx: Optional[RequestContext] = None) -> str:return run_async(self.get_status_table_async(ctx=ctx))+ def get_status_json(self, ctx: Optional[RequestContext] = None) -> dict:+ return run_async(self.get_status_json_async(ctx=ctx))+def __str__(self) -> str:return self.get_status_table()diff --git a/sdk/go/client_test.go b/sdk/go/client_test.goindex 82cb14bba..03afea160 100644--- a/sdk/go/client_test.go+++ b/sdk/go/client_test.go@@ -1754,6 +1754,65 @@ func TestHealth(t *testing.T) {}}+func TestObserverStatusSupportsOptionalFormat(t *testing.T) {+ requests := 0+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ requests+++ switch requests {+ case 1:+ if r.URL.Path != "/api/v1/observer/system" {+ t.Fatalf("path = %s", r.URL.Path)+ }+ if got := r.URL.Query().Get("format"); got != "" {+ t.Fatalf("format = %q", got)+ }+ writeOK(t, w, map[string]any{"is_healthy": true})+ case 2:+ if r.URL.Path != "/api/v1/observer/queue" {+ t.Fatalf("path = %s", r.URL.Path)+ }+ if got := r.URL.Query().Get("format"); got != "json" {+ t.Fatalf("format = %q", got)+ }+ writeOK(t, w, map[string]any{"name": "queue"})+ case 3:+ if r.URL.Path != "/api/v1/observer/models" {+ t.Fatalf("path = %s", r.URL.Path)+ }+ if got := r.URL.Query().Get("format"); got != "table" {+ t.Fatalf("format = %q", got)+ }+ writeOK(t, w, map[string]any{"name": "models"})+ default:+ t.Fatalf("unexpected request %d: %s", requests, r.URL.String())+ }+ }))+ defer closeServer()++ status, err := client.GetStatus(context.Background())+ if err != nil {+ t.Fatal(err)+ }+ queue, err := client.QueueStatus(context.Background(), ObserverStatusOptions{Format: "json"})+ if err != nil {+ t.Fatal(err)+ }+ models, err := client.ModelsStatus(context.Background(), ObserverStatusOptions{Format: "table"})+ if err != nil {+ t.Fatal(err)+ }++ if status["is_healthy"] != true {+ t.Fatalf("status = %#v", status)+ }+ if queue["name"] != "queue" {+ t.Fatalf("queue = %#v", queue)+ }+ if models["name"] != "models" {+ t.Fatalf("models = %#v", models)+ }+}+func TestSetTagsSendsBody(t *testing.T) {client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {if r.URL.Path != "/api/v1/fs/attrs/set_tags" {diff --git a/sdk/go/system.go b/sdk/go/system.goindex 62c7157a0..621861710 100644--- a/sdk/go/system.go+++ b/sdk/go/system.go@@ -4,6 +4,7 @@ import ("context""encoding/json""net/http"+ "net/url")// WaitProcessed waits until all queued processing completes.@@ -48,28 +49,33 @@ func (c *Client) Health(ctx context.Context) (bool, error) {}// QueueStatus returns queue observer status.-func (c *Client) QueueStatus(ctx context.Context) (map[string]any, error) {- return c.observerStatus(ctx, "/api/v1/observer/queue")+func (c *Client) QueueStatus(ctx context.Context, options ...ObserverStatusOptions) (map[string]any, error) {+ return c.observerStatus(ctx, "/api/v1/observer/queue", options...)}// VikingDBStatus returns vector DB observer status.-func (c *Client) VikingDBStatus(ctx context.Context) (map[string]any, error) {- return c.observerStatus(ctx, "/api/v1/observer/vikingdb")+func (c *Client) VikingDBStatus(ctx context.Context, options ...ObserverStatusOptions) (map[string]any, error) {+ return c.observerStatus(ctx, "/api/v1/observer/vikingdb", options...)}// ModelsStatus returns model observer status.-func (c *Client) ModelsStatus(ctx context.Context) (map[string]any, error) {- return c.observerStatus(ctx, "/api/v1/observer/models")+func (c *Client) ModelsStatus(ctx context.Context, options ...ObserverStatusOptions) (map[string]any, error) {+ return c.observerStatus(ctx, "/api/v1/observer/models", options...)}// GetStatus returns overall observer status.-func (c *Client) GetStatus(ctx context.Context) (map[string]any, error) {- return c.observerStatus(ctx, "/api/v1/observer/system")+func (c *Client) GetStatus(ctx context.Context, options ...ObserverStatusOptions) (map[string]any, error) {+ return c.observerStatus(ctx, "/api/v1/observer/system", options...)}-func (c *Client) observerStatus(ctx context.Context, path string) (map[string]any, error) {+func (c *Client) observerStatus(ctx context.Context, path string, options ...ObserverStatusOptions) (map[string]any, error) {+ var query url.Values+ if len(options) > 0 && options[0].Format != "" {+ query = url.Values{}+ query.Set("format", options[0].Format)+ }var result map[string]any- err := c.doJSON(ctx, http.MethodGet, path, nil, nil, &result)+ err := c.doJSON(ctx, http.MethodGet, path, query, nil, &result)return result, err}diff --git a/sdk/go/types.go b/sdk/go/types.goindex 351720051..857d5b74f 100644--- a/sdk/go/types.go+++ b/sdk/go/types.go@@ -154,6 +154,11 @@ type WaitProcessedOptions struct {Timeout *float64 `json:"timeout,omitempty"`}+// ObserverStatusOptions controls observer status formatting.+type ObserverStatusOptions struct {+ Format string+}+// ListWatchesOptions controls ListWatches.type ListWatchesOptions struct {ActiveOnly booldiff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.pyindex 58dfce6b6..87640f2e3 100644--- a/sdk/python/openviking_sdk/client.py+++ b/sdk/python/openviking_sdk/client.py@@ -1793,20 +1793,32 @@ class AsyncHTTPClient:)return self._handle_response(response)- async def _get_queue_status(self) -> Dict[str, Any]:- response = await self._request("GET", "/api/v1/observer/queue")+ async def _get_queue_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ params = {"format": format} if format is not None else None+ response = await self._request("GET", "/api/v1/observer/queue", params=params)return self._handle_response(response)- async def _get_vikingdb_status(self) -> Dict[str, Any]:- response = await self._request("GET", "/api/v1/observer/vikingdb")+ async def _get_vikingdb_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ params = {"format": format} if format is not None else None+ response = await self._request("GET", "/api/v1/observer/vikingdb", params=params)return self._handle_response(response)- async def _get_models_status(self) -> Dict[str, Any]:- response = await self._request("GET", "/api/v1/observer/models")+ async def _get_models_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ params = {"format": format} if format is not None else None+ response = await self._request("GET", "/api/v1/observer/models", params=params)return self._handle_response(response)- async def _get_system_status(self) -> Dict[str, Any]:- response = await self._request("GET", "/api/v1/observer/system")+ async def _get_system_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ params = {"format": format} if format is not None else None+ response = await self._request("GET", "/api/v1/observer/system", params=params)return self._handle_response(response)async def admin_create_account(@@ -2058,8 +2070,25 @@ class AsyncHTTPClient:)return self._handle_response(response)- def get_status(self) -> Dict[str, Any]:- return run_async(self._get_system_status())+ def queue_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return run_async(self._get_queue_status(format=format))++ def vikingdb_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return run_async(self._get_vikingdb_status(format=format))++ def models_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return run_async(self._get_models_status(format=format))++ def get_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return run_async(self._get_system_status(format=format))def is_healthy(self) -> bool:return self.observer.is_healthy()@@ -2981,8 +3010,25 @@ class SyncHTTPClient:) -> Dict[str, Any]:return run_async(self._async_client.preflight_openviking_asset(name, repo_url, options))- def get_status(self) -> Dict[str, Any]:- return self._async_client.get_status()+ def queue_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return self._async_client.queue_status(format=format)++ def vikingdb_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return self._async_client.vikingdb_status(format=format)++ def models_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return self._async_client.models_status(format=format)++ def get_status(+ self, format: Optional[Literal["table", "json"]] = None+ ) -> Dict[str, Any]:+ return self._async_client.get_status(format=format)def is_healthy(self) -> bool:return self._async_client.is_healthy()diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.pyindex 930f0fa1b..4935b6c2e 100644--- a/sdk/python/tests/test_async_client_behaviors.py+++ b/sdk/python/tests/test_async_client_behaviors.py@@ -682,6 +682,20 @@ def test_sync_http_client_get_status_does_not_require_run_async():assert status == {"is_healthy": True}+def test_sync_http_client_observer_methods_accept_format():+ client = SyncHTTPClient(url="http://localhost:1933")+ client._async_client._get_queue_status = AsyncMock(return_value={"name": "queue"})+ client._async_client._get_system_status = AsyncMock(return_value={"is_healthy": True})++ queue_status = client.queue_status(format="json")+ system_status = client.get_status(format="json")++ assert queue_status == {"name": "queue"}+ assert system_status == {"is_healthy": True}+ client._async_client._get_queue_status.assert_awaited_once_with(format="json")+ client._async_client._get_system_status.assert_awaited_once_with(format="json")++def test_sync_http_client_health_wraps_async_coroutine():client = SyncHTTPClient(url="http://localhost:1933")client._async_client.health = AsyncMock(return_value=True)@@ -689,6 +703,45 @@ def test_sync_http_client_health_wraps_async_coroutine():assert client.health() is True+ ("method_name", "format_value", "expected_path", "expected_params"),+ [+ ("_get_queue_status", None, "/api/v1/observer/queue", None),+ ("_get_queue_status", "json", "/api/v1/observer/queue", {"format": "json"}),+ ("_get_vikingdb_status", "json", "/api/v1/observer/vikingdb", {"format": "json"}),+ ("_get_models_status", "table", "/api/v1/observer/models", {"format": "table"}),+ ("_get_system_status", None, "/api/v1/observer/system", None),+ ],+)+async def test_async_http_client_observer_requests_support_optional_format(+ method_name, format_value, expected_path, expected_params+):+ client = AsyncHTTPClient(url="http://localhost:1933")+ client._request = AsyncMock(return_value=object())+ client._handle_response_data = lambda _response: {"result": {"ok": True}}++ method = getattr(client, method_name)+ if format_value is None:+ result = await method()+ else:+ result = await method(format=format_value)++ assert result == {"ok": True}+ if expected_params is None:+ client._request.assert_awaited_once_with(+ "GET",+ expected_path,+ params=None,+ )+ else:+ client._request.assert_awaited_once_with(+ "GET",+ expected_path,+ params=expected_params,+ )++@pytest.mark.asyncioasync def test_write_omits_removed_semantic_flags_from_http_payload():client = AsyncHTTPClient(url="http://localhost:1933")diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.tsindex 170985c4e..fd536af1a 100644--- a/sdk/typescript/src/client.ts+++ b/sdk/typescript/src/client.ts@@ -29,6 +29,7 @@ import type {GlobOptions,ImportPackOptions,Message,+ ObserverFormat,PreflightAssetOptions,ReindexOptions,RequestOptions,@@ -1020,20 +1021,28 @@ export class OpenVikingClient {});}/** Return aggregate observer status. */- getStatus(): Promise<JsonObject> {- return this.request("GET", "/api/v1/observer/system");+ getStatus(format?: ObserverFormat): Promise<JsonObject> {+ return this.request("GET", "/api/v1/observer/system", {+ query: { format },+ });}/** Return queue observer status. */- queueStatus(): Promise<JsonObject> {- return this.request("GET", "/api/v1/observer/queue");+ queueStatus(format?: ObserverFormat): Promise<JsonObject> {+ return this.request("GET", "/api/v1/observer/queue", {+ query: { format },+ });}/** Return VikingDB observer status. */- vikingDBStatus(): Promise<JsonObject> {- return this.request("GET", "/api/v1/observer/vikingdb");+ vikingDBStatus(format?: ObserverFormat): Promise<JsonObject> {+ return this.request("GET", "/api/v1/observer/vikingdb", {+ query: { format },+ });}/** Return model observer status. */- modelsStatus(): Promise<JsonObject> {- return this.request("GET", "/api/v1/observer/models");+ modelsStatus(format?: ObserverFormat): Promise<JsonObject> {+ return this.request("GET", "/api/v1/observer/models", {+ query: { format },+ });}/** Return whether the observer system reports healthy. */async isHealthy(): Promise<boolean> {diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.tsindex 75d6d6dd0..8715f7eca 100644--- a/sdk/typescript/src/types.ts+++ b/sdk/typescript/src/types.ts@@ -9,6 +9,8 @@ export type ClientHeaders =export type UploadMode = "local" | "shared";/** Resource post-ingest processing modes accepted by addResource. */export type ProcessingMode = "semantic_and_vectors" | "vectors_only";+/** Observer response format supported by HTTP observer APIs. */+export type ObserverFormat = "table" | "json";/** Conflict policy accepted when importing an OVPack. */export type PackConflictPolicy = "fail" | "overwrite" | "skip";/** Vector handling strategy accepted when importing an OVPack. */diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.tsindex febbe85fb..285c08d8d 100644--- a/sdk/typescript/tests/client.test.ts+++ b/sdk/typescript/tests/client.test.ts@@ -1216,6 +1216,34 @@ describe("OpenVikingClient", () => {});});+ it("supports optional observer format query parameters", async () => {+ const fetcher = vi+ .fn<typeof fetch>()+ .mockResolvedValueOnce(ok({ is_healthy: true }))+ .mockResolvedValueOnce(ok({ name: "queue" }))+ .mockResolvedValueOnce(ok({ name: "models" }));+ const client = new OpenVikingClient({+ baseUrl: "https://example.com",+ fetch: fetcher,+ });++ await expect(client.getStatus()).resolves.toEqual({ is_healthy: true });+ await expect(client.queueStatus("json")).resolves.toEqual({ name: "queue" });+ await expect(client.modelsStatus("table")).resolves.toEqual({+ name: "models",+ });++ const first = new URL(String(fetcher.mock.calls[0]![0]));+ const second = new URL(String(fetcher.mock.calls[1]![0]));+ const third = new URL(String(fetcher.mock.calls[2]![0]));+ expect(first.pathname).toBe("/api/v1/observer/system");+ expect(first.searchParams.get("format")).toBeNull();+ expect(second.pathname).toBe("/api/v1/observer/queue");+ expect(second.searchParams.get("format")).toBe("json");+ expect(third.pathname).toBe("/api/v1/observer/models");+ expect(third.searchParams.get("format")).toBe("table");+ });+it("supports snapshot restore, binary show, log, diff and ignore operations", async () => {const fetcher = vi.fn<typeof fetch>()diff --git a/tests/misc/test_debug_service.py b/tests/misc/test_debug_service.pyindex 922e59068..2a1ceb4e8 100644--- a/tests/misc/test_debug_service.py+++ b/tests/misc/test_debug_service.py@@ -375,6 +375,46 @@ class TestObserverService:assert status.has_errors is Trueassert status.status == "Not initialized"+ def test_queue_json_status_without_dependency_is_structured(self):+ """Test queue json format returns a structured payload when uninitialized."""+ service = ObserverService()+ with patch("openviking.service.debug_service.get_queue_manager", side_effect=RuntimeError()):+ status = service.get_queue_status(format="json")+ assert isinstance(status, ComponentStatus)+ assert status.name == "queue"+ assert status.is_healthy is False+ assert status.has_errors is True+ assert status.status == {+ "queues": [],+ "summary": {+ "pending": 0,+ "in_progress": 0,+ "processed": 0,+ "requeued": 0,+ "errors": 0,+ "total": 0,+ },+ "error": "Not initialized",+ }++ def test_vikingdb_json_status_without_dependency_is_structured(self):+ """Test vikingdb json format returns a structured payload when uninitialized."""+ service = ObserverService()+ status = service.get_vikingdb_status(format="json")+ assert isinstance(status, ComponentStatus)+ assert status.name == "vikingdb"+ assert status.is_healthy is False+ assert status.has_errors is True+ assert status.status == {+ "collections": [],+ "summary": {+ "index_count": 0,+ "vector_count": 0,+ "collection_count": 0,+ },+ "error": "Not initialized",+ }+def test_models_property_without_dependency(self):"""Test models property returns unhealthy ComponentStatus when config is None."""service = ObserverService()@@ -385,6 +425,53 @@ class TestObserverService:assert status.has_errors is Trueassert status.status == "Not initialized"+ def test_models_json_status_without_dependency_is_structured(self):+ """Test models json format returns a structured payload when uninitialized."""+ service = ObserverService()+ status = service.get_models_status(format="json")+ assert isinstance(status, ComponentStatus)+ assert status.name == "models"+ assert status.is_healthy is False+ assert status.has_errors is True+ assert status.status == {+ "vlm": [],+ "embedding": [],+ "rerank": [],+ "error": "Not initialized",+ }++ def test_models_property_delegates_to_get_models_status(self):+ """Test models property reuses the explicit status collection path."""+ service = ObserverService()+ expected = ComponentStatus(+ name="models",+ is_healthy=True,+ has_errors=False,+ status="table-status",+ )++ with patch.object(service, "get_models_status", return_value=expected) as mock_get_status:+ status = service.models++ assert status is expected+ mock_get_status.assert_called_once_with()++ def test_lock_json_status_without_dependency_is_structured(self):+ """Test lock json format returns a structured payload when uninitialized."""+ service = ObserverService()+ status = service.get_lock_status(format="json")+ assert isinstance(status, ComponentStatus)+ assert status.name == "lock"+ assert status.is_healthy is False+ assert status.has_errors is True+ assert status.status == {+ "active_locks": 0,+ "waiting_locks": 0,+ "stale_locks_removed": 0,+ "conflict_count": 0,+ "error": "Not initialized",+ }+def test_system_property_without_dependencies(self):"""Test system property returns unhealthy SystemStatus when dependencies not set."""service = ObserverService()diff --git a/tests/server/test_api_observer.py b/tests/server/test_api_observer.pyindex 18d58573e..dd6bc62b0 100644--- a/tests/server/test_api_observer.py+++ b/tests/server/test_api_observer.py@@ -19,6 +19,21 @@ async def test_observer_queue(client: httpx.AsyncClient):assert "status" in result+async def test_observer_queue_structured(client: httpx.AsyncClient):+ """GET /api/v1/observer/queue?format=json should return structured status."""+ resp = await client.get("/api/v1/observer/queue", params={"format": "json"})+ assert resp.status_code == 200+ body = resp.json()+ assert body["status"] == "ok"+ result = body["result"]+ assert "status" in result+ assert isinstance(result["status"], dict)+ assert "queues" in result["status"]+ assert isinstance(result["status"]["queues"], list)+ assert "summary" in result["status"]+ assert isinstance(result["status"]["summary"], dict)++async def test_observer_vikingdb(client: httpx.AsyncClient):"""GET /api/v1/observer/vikingdb should return VikingDB status."""resp = await client.get("/api/v1/observer/vikingdb")@@ -52,3 +67,16 @@ async def test_observer_system(client: httpx.AsyncClient):assert "errors" in resultassert "components" in resultassert isinstance(result["components"], dict)+++async def test_observer_system_structured(client: httpx.AsyncClient):+ """GET /api/v1/observer/system?format=json should include structured component payloads."""+ resp = await client.get("/api/v1/observer/system", params={"format": "json"})+ assert resp.status_code == 200+ body = resp.json()+ assert body["status"] == "ok"+ result = body["result"]+ assert "components" in result+ queue = result["components"]["queue"]+ assert "status" in queue+ assert isinstance(queue["status"], dict)diff --git a/tests/storage/test_queue_observer.py b/tests/storage/test_queue_observer.pyindex c928bbe1b..97fcadf06 100644--- a/tests/storage/test_queue_observer.py+++ b/tests/storage/test_queue_observer.py@@ -77,3 +77,55 @@ def test_queue_errors_make_in_progress_queue_unhealthy() -> None:assert observer.has_errors() is Trueassert observer.is_healthy() is False+++class _TreeStats:+ total_nodes = 9+ pending_nodes = 1+ in_progress_nodes = 0+ done_nodes = 8+++class _FakeSemanticHandler:+ @staticmethod+ def get_tree_stats():+ return _TreeStats()+++class _FakeSemanticQueue:+ _dequeue_handler = _FakeSemanticHandler()+++def test_status_json_summary_matches_table_totals() -> None:+ queue_manager = _FakeQueueManager(+ {+ "Semantic": QueueStatus(+ pending=0,+ in_progress=0,+ processed=2,+ error_count=0,+ )+ }+ )+ queue_manager._queues = {queue_manager.SEMANTIC: _FakeSemanticQueue()}+ observer = QueueObserver(queue_manager)++ status = observer.get_status_json()++ assert status["queues"][-1] == {+ "queue": "Semantic-Nodes",+ "pending": 1,+ "in_progress": 0,+ "processed": 8,+ "requeued": 0,+ "errors": 0,+ "total": 9,+ }+ assert status["summary"] == {+ "pending": 0,+ "in_progress": 0,+ "processed": 2,+ "requeued": 0,+ "errors": 0,+ "total": 2,+ }