Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(observer): support JSON status format (#5316)

Jiahui Zhou34326306c139
diff --git a/openviking/server/routers/observer.py b/openviking/server/routers/observer.py
index 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, Query
from openviking.server.auth import get_request_context
from 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.py
index 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_logger
logger = 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"
+
+
@dataclass
class ComponentStatus:
"""Component status."""
@@ -32,7 +86,7 @@ class ComponentStatus:
name: str
is_healthy: bool
has_errors: bool
- status: str
+ status: Any
def __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 = True
return 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)
+
@property
def 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 = None
rerank_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,
+ )
+
@property
def 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(),
+ )
+
@property
def 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.py
index 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 Any
class 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.abstractmethod
def is_healthy(self) -> bool:
"""
diff --git a/openviking/storage/observers/filesystem_observer.py b/openviking/storage/observers/filesystem_observer.py
index 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.py
index 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.py
index 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.py
index 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 tabulate
diff --git a/openviking/storage/observers/vikingdb_observer.py b/openviking/storage/observers/vikingdb_observer.py
index 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.go
index 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.go
index 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.go
index 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 bool
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index 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.py
index 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.asyncio
async 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.ts
index 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.ts
index 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.ts
index 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.py
index 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 True
assert 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 True
assert 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.py
index 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 result
assert "components" in result
assert 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.py
index 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 True
assert 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,
+ }