feat: add api discovery capability skeleton

这个提交存在于:
YokiiroBW 2026-07-05 10:07:12 +08:00
父节点 ef202f9be7
当前提交 935cd1b3d4
共有 5 个文件被更改,包括 476 次插入 和 0 次删除

查看文件

@ -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))

查看文件

@ -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}"

查看文件

@ -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);

查看文件

@ -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)

查看文件

@ -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()