From 935cd1b3d4253dde7d75edccf86854aad069e078 Mon Sep 17 00:00:00 2001 From: YokiiroBW Date: Sun, 5 Jul 2026 10:07:12 +0800 Subject: [PATCH] feat: add api discovery capability skeleton --- backend/routes/api_discovery_routes.py | 65 +++++++ backend/services/api_discovery_service.py | 114 +++++++++++++ .../migrations/0011_capability_profiles.sql | 14 ++ .../repositories/capability_repository.py | 159 ++++++++++++++++++ tests/test_api_discovery_service.py | 124 ++++++++++++++ 5 files changed, 476 insertions(+) create mode 100644 backend/routes/api_discovery_routes.py create mode 100644 backend/services/api_discovery_service.py create mode 100644 database/migrations/0011_capability_profiles.sql create mode 100644 database/repositories/capability_repository.py create mode 100644 tests/test_api_discovery_service.py diff --git a/backend/routes/api_discovery_routes.py b/backend/routes/api_discovery_routes.py new file mode 100644 index 0000000..a6e1924 --- /dev/null +++ b/backend/routes/api_discovery_routes.py @@ -0,0 +1,65 @@ +"""API discovery route handlers.""" + +from __future__ import annotations + +from typing import Any + +from backend.routes.common import handle_request +from backend.services.api_discovery_service import ApiDiscoveryService +from core.identity import RequestContext +from core.security import require_authenticated, require_config_manager +from database.db_helper import Database, load_database_settings +from database.repositories.capability_repository import CapabilityRepository + + +def list_dialects(ctx: RequestContext, service: ApiDiscoveryService | None = None) -> dict: + discovery_service = service or _create_discovery_service() + + def action() -> list[dict[str, Any]]: + require_authenticated(ctx) + return discovery_service.dialects() + + return handle_request(ctx, action) + + +def probe_provider( + ctx: RequestContext, + payload: dict[str, Any], + service: ApiDiscoveryService | None = None, +) -> dict: + discovery_service = service or _create_discovery_service() + + def action() -> dict[str, Any]: + require_config_manager(ctx) + return discovery_service.probe_provider(payload) + + return handle_request(ctx, action) + + +def list_capabilities(ctx: RequestContext, service: ApiDiscoveryService | None = None) -> dict: + discovery_service = service or _create_discovery_service() + + def action() -> list[dict[str, Any]]: + require_authenticated(ctx) + return discovery_service.capabilities() + + return handle_request(ctx, action) + + +def validate_render_plan( + ctx: RequestContext, + payload: dict[str, Any], + service: ApiDiscoveryService | None = None, +) -> dict: + discovery_service = service or _create_discovery_service() + + def action() -> dict[str, Any]: + require_authenticated(ctx) + return discovery_service.validate_render_plan(payload) + + return handle_request(ctx, action) + + +def _create_discovery_service() -> ApiDiscoveryService: + database = Database(load_database_settings()) + return ApiDiscoveryService(CapabilityRepository(database)) diff --git a/backend/services/api_discovery_service.py b/backend/services/api_discovery_service.py new file mode 100644 index 0000000..7befb44 --- /dev/null +++ b/backend/services/api_discovery_service.py @@ -0,0 +1,114 @@ +"""Safe API discovery and render-plan validation.""" + +from __future__ import annotations + +from typing import Any +from uuid import uuid4 + +from backend.dto.common import ApiError, ErrorCode +from database.repositories.capability_repository import CapabilityRepository + + +DIALECTS = [ + { + "dialect": "openai_images", + "label": "OpenAI Images compatible", + "capabilities": ["text_to_image", "image_edit", "mask_edit"], + }, + { + "dialect": "comfyui", + "label": "ComfyUI workflow", + "capabilities": ["text_to_image", "workflow_graph"], + }, + { + "dialect": "unknown", + "label": "Unconfirmed backend", + "capabilities": [], + }, +] + + +class ApiDiscoveryService: + def __init__(self, repository: CapabilityRepository): + self.repository = repository + + def dialects(self) -> list[dict[str, Any]]: + return DIALECTS + + def probe_provider(self, payload: dict[str, Any]) -> dict[str, Any]: + provider_id = str(payload.get("provider_id") or "").strip() + model_id = str(payload.get("model_id") or "").strip() + if not provider_id: + raise ApiError(ErrorCode.VALIDATION_FAILED, "provider_id is required", {"field": "provider_id"}) + if not model_id: + raise ApiError(ErrorCode.VALIDATION_FAILED, "model_id is required", {"field": "model_id"}) + dialect = str(payload.get("dialect") or "unknown") + profile = self.repository.upsert_profile( + { + "capability_profile_id": payload.get("capability_profile_id") or new_capability_profile_id(), + "provider_id": provider_id, + "model_id": model_id, + "dialect": dialect, + "status": "unconfirmed", + "capabilities": payload.get("capabilities") or {}, + "probe_result": { + "mode": "safe", + "message": "safe probe recorded metadata only; no external API call was made", + }, + } + ) + return profile + + def capabilities(self) -> list[dict[str, Any]]: + return self.repository.list_profiles() + + def validate_render_plan(self, payload: dict[str, Any]) -> dict[str, Any]: + provider_id = str(payload.get("provider_id") or "").strip() + model_id = str(payload.get("model_id") or "").strip() + required = [str(item) for item in payload.get("required_capabilities") or []] + profile = self.repository.get_profile(provider_id, model_id) if provider_id and model_id else None + if profile is None: + return { + "valid": False, + "status": "unconfirmed", + "errors": [ + { + "code": ErrorCode.MODEL_CAPABILITY_UNCONFIRMED.value, + "message": "model capability profile is unconfirmed", + } + ], + "warnings": [], + } + if profile["status"] != "confirmed_supported": + return { + "valid": False, + "status": profile["status"], + "errors": [ + { + "code": ErrorCode.MODEL_CAPABILITY_UNCONFIRMED.value, + "message": "model capabilities are not confirmed", + } + ], + "warnings": [], + "profile": profile, + } + supported = set(profile["capabilities"].get("supports", [])) + missing = [capability for capability in required if capability not in supported] + return { + "valid": not missing, + "status": profile["status"], + "errors": [ + { + "code": ErrorCode.MODEL_CAPABILITY_UNSUPPORTED.value, + "message": "required capability is not supported", + "capability": capability, + } + for capability in missing + ], + "warnings": [], + "profile": profile, + } + + +def new_capability_profile_id() -> str: + return f"cap_{uuid4().hex}" diff --git a/database/migrations/0011_capability_profiles.sql b/database/migrations/0011_capability_profiles.sql new file mode 100644 index 0000000..d8bd22b --- /dev/null +++ b/database/migrations/0011_capability_profiles.sql @@ -0,0 +1,14 @@ +CREATE TABLE IF NOT EXISTS backend_capability_profiles ( + capability_profile_id TEXT PRIMARY KEY, + provider_id TEXT NOT NULL, + model_id TEXT NOT NULL, + dialect TEXT NOT NULL DEFAULT 'unknown', + status TEXT NOT NULL DEFAULT 'unconfirmed', + capabilities_json TEXT, + probe_result_json TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +CREATE UNIQUE INDEX IF NOT EXISTS idx_capability_profiles_provider_model + ON backend_capability_profiles(provider_id, model_id); diff --git a/database/repositories/capability_repository.py b/database/repositories/capability_repository.py new file mode 100644 index 0000000..6bc89f6 --- /dev/null +++ b/database/repositories/capability_repository.py @@ -0,0 +1,159 @@ +"""Repository for backend capability profiles.""" + +from __future__ import annotations + +import json +from typing import Any + +from database.db_helper import Database + + +class CapabilityRepository: + def __init__(self, database: Database): + self.database = database + + @property + def placeholder(self) -> str: + return self.database._placeholder + + def upsert_profile(self, payload: dict[str, Any]) -> dict[str, Any]: + existing = self.get_profile(payload["provider_id"], payload["model_id"]) + if existing: + return self.update_profile(existing["capability_profile_id"], payload) or existing + placeholder = self.placeholder + conn = self.database.connect() + try: + conn.execute( + f""" + INSERT INTO backend_capability_profiles ( + capability_profile_id, + provider_id, + model_id, + dialect, + status, + capabilities_json, + probe_result_json + ) VALUES ( + {placeholder}, {placeholder}, {placeholder}, {placeholder}, + {placeholder}, {placeholder}, {placeholder} + ) + """, + ( + payload["capability_profile_id"], + payload["provider_id"], + payload["model_id"], + payload.get("dialect", "unknown"), + payload.get("status", "unconfirmed"), + _json_or_none(payload.get("capabilities") or {}), + _json_or_none(payload.get("probe_result") or {}), + ), + ) + conn.commit() + finally: + conn.close() + return self.get_profile(payload["provider_id"], payload["model_id"]) or payload + + def update_profile(self, capability_profile_id: str, payload: dict[str, Any]) -> dict[str, Any] | None: + allowed = {"dialect", "status", "capabilities", "probe_result"} + assignments: list[str] = [] + params: list[Any] = [] + placeholder = self.placeholder + for key in allowed: + if key not in payload: + continue + column = key + value = payload[key] + if key == "capabilities": + column = "capabilities_json" + value = _json_or_none(value or {}) + elif key == "probe_result": + column = "probe_result_json" + value = _json_or_none(value or {}) + assignments.append(f"{column} = {placeholder}") + params.append(value) + if not assignments: + return self.get_by_id(capability_profile_id) + assignments.append("updated_at = CURRENT_TIMESTAMP") + params.append(capability_profile_id) + conn = self.database.connect() + try: + conn.execute( + f""" + UPDATE backend_capability_profiles + SET {", ".join(assignments)} + WHERE capability_profile_id = {placeholder} + """, + tuple(params), + ) + conn.commit() + finally: + conn.close() + return self.get_by_id(capability_profile_id) + + def get_profile(self, provider_id: str, model_id: str) -> dict[str, Any] | None: + placeholder = self.placeholder + conn = self.database.connect() + try: + row = conn.execute( + f""" + SELECT * + FROM backend_capability_profiles + WHERE provider_id = {placeholder} AND model_id = {placeholder} + """, + (provider_id, model_id), + ).fetchone() + finally: + conn.close() + return _row_to_profile(row) if row else None + + def get_by_id(self, capability_profile_id: str) -> dict[str, Any] | None: + placeholder = self.placeholder + conn = self.database.connect() + try: + row = conn.execute( + f"SELECT * FROM backend_capability_profiles WHERE capability_profile_id = {placeholder}", + (capability_profile_id,), + ).fetchone() + finally: + conn.close() + return _row_to_profile(row) if row else None + + def list_profiles(self) -> list[dict[str, Any]]: + conn = self.database.connect() + try: + rows = conn.execute( + """ + SELECT * + FROM backend_capability_profiles + ORDER BY provider_id ASC, model_id ASC + """ + ).fetchall() + finally: + conn.close() + return [_row_to_profile(row) for row in rows] + + +def _row_to_profile(row) -> dict[str, Any]: + return { + "capability_profile_id": row["capability_profile_id"], + "provider_id": row["provider_id"], + "model_id": row["model_id"], + "dialect": row["dialect"], + "status": row["status"], + "capabilities": _json_loads(row["capabilities_json"]), + "probe_result": _json_loads(row["probe_result_json"]), + "created_at": str(row["created_at"]), + "updated_at": str(row["updated_at"]), + } + + +def _json_or_none(value: Any | None) -> str | None: + if value is None: + return None + return json.dumps(value, ensure_ascii=False, sort_keys=True) + + +def _json_loads(value: str | None) -> dict[str, Any]: + if not value: + return {} + return json.loads(value) diff --git a/tests/test_api_discovery_service.py b/tests/test_api_discovery_service.py new file mode 100644 index 0000000..33abb24 --- /dev/null +++ b/tests/test_api_discovery_service.py @@ -0,0 +1,124 @@ +from __future__ import annotations + +import tempfile +import unittest +from pathlib import Path + +from backend.routes.api_discovery_routes import list_capabilities, list_dialects, probe_provider, validate_render_plan +from backend.services.api_discovery_service import ApiDiscoveryService +from core.identity import RequestContext +from database.db_helper import Database, DatabaseSettings, SqliteSettings +from database.repositories.capability_repository import CapabilityRepository + + +class ApiDiscoveryServiceTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.database = Database( + DatabaseSettings(sqlite=SqliteSettings(path=str(Path(self.tmp.name) / "imagestudio.db"))) + ) + self.database.initialize() + self.repository = CapabilityRepository(self.database) + self.service = ApiDiscoveryService(self.repository) + self.ctx = RequestContext.from_astrbot( + username="admin", + user_id="user_001", + permissions={"can_manage_config"}, + ) + + def tearDown(self): + self.tmp.cleanup() + + def test_safe_probe_records_unconfirmed_profile(self): + profile = self.service.probe_provider( + { + "provider_id": "local_provider", + "model_id": "image_low", + "dialect": "openai_images", + "capabilities": {"supports": ["text_to_image"]}, + } + ) + + self.assertEqual(profile["status"], "unconfirmed") + self.assertEqual(profile["probe_result"]["mode"], "safe") + self.assertEqual(len(self.service.capabilities()), 1) + + def test_render_plan_treats_missing_profile_as_unconfirmed(self): + result = self.service.validate_render_plan( + { + "provider_id": "missing", + "model_id": "image_low", + "required_capabilities": ["text_to_image"], + } + ) + + self.assertFalse(result["valid"]) + self.assertEqual(result["status"], "unconfirmed") + self.assertEqual(result["errors"][0]["code"], "MODEL_CAPABILITY_UNCONFIRMED") + + def test_render_plan_checks_confirmed_supported_capabilities(self): + profile = self.service.probe_provider( + { + "provider_id": "local_provider", + "model_id": "image_low", + "dialect": "openai_images", + "capabilities": {"supports": ["text_to_image"]}, + } + ) + self.repository.update_profile(profile["capability_profile_id"], {"status": "confirmed_supported"}) + + valid = self.service.validate_render_plan( + { + "provider_id": "local_provider", + "model_id": "image_low", + "required_capabilities": ["text_to_image"], + } + ) + self.assertTrue(valid["valid"]) + + invalid = self.service.validate_render_plan( + { + "provider_id": "local_provider", + "model_id": "image_low", + "required_capabilities": ["image_edit"], + } + ) + self.assertFalse(invalid["valid"]) + self.assertEqual(invalid["errors"][0]["code"], "MODEL_CAPABILITY_UNSUPPORTED") + + def test_api_discovery_routes_wrap_responses(self): + dialects = list_dialects(self.ctx, self.service) + self.assertTrue(dialects["ok"]) + self.assertIn("unknown", [item["dialect"] for item in dialects["data"]]) + + probed = probe_provider( + self.ctx, + {"provider_id": "local_provider", "model_id": "image_low"}, + self.service, + ) + self.assertTrue(probed["ok"]) + + capabilities = list_capabilities(self.ctx, self.service) + self.assertTrue(capabilities["ok"]) + self.assertEqual(len(capabilities["data"]), 1) + + validation = validate_render_plan( + self.ctx, + { + "provider_id": "local_provider", + "model_id": "image_low", + "required_capabilities": ["text_to_image"], + }, + self.service, + ) + self.assertTrue(validation["ok"]) + self.assertEqual(validation["data"]["status"], "unconfirmed") + + read_only = RequestContext.from_astrbot(username="viewer", user_id="viewer_001") + denied = probe_provider(read_only, {"provider_id": "x", "model_id": "y"}, self.service) + self.assertFalse(denied["ok"]) + self.assertEqual(denied["error_code"], "FORBIDDEN") + + +if __name__ == "__main__": + unittest.main()