web_models.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591
  1. """Pydantic request/response models for the Hermes dashboard web server."""
  2. from __future__ import annotations
  3. import math
  4. from typing import Any, Dict, List, Literal, Optional, Union
  5. from pydantic import BaseModel, Field, SecretStr, StrictBool, StrictInt, field_validator
  6. class ConfigUpdate(BaseModel):
  7. config: dict
  8. profile: Optional[str] = None
  9. class EnvVarUpdate(BaseModel):
  10. key: str
  11. value: str
  12. profile: Optional[str] = None
  13. # Bearer for the OPENAI_BASE_URL connectivity probe (auth-gated /v1/models otherwise looks
  14. # "reachable but empty"); ignored by plain PUT /api/env.
  15. api_key: str = ""
  16. # Sent by the Desktop's provider-connection forms: a key a tool panel also asks for (Gemini,
  17. # xAI...) then still counts as a provider setup in shared metrics.
  18. provider_setup: bool = False
  19. class EnvVarDelete(BaseModel):
  20. key: str
  21. profile: Optional[str] = None
  22. class EnvVarReveal(EnvVarDelete):
  23. pass
  24. class MemoryProviderConfigUpdate(BaseModel):
  25. values: dict[str, Any] = {}
  26. class MemoryProviderSetupRequest(BaseModel):
  27. values: dict[str, Any] = {}
  28. class CustomEndpointModelDetail(BaseModel):
  29. """One ``/v1/models`` row with the routing metadata a gateway may advertise on a
  30. reasoning alias (``gpt-5.6-sol-high`` → ``gpt-5.6-sol`` @ ``high``). See #93622."""
  31. id: str
  32. canonical_model: Optional[str] = None
  33. reasoning_effort: Optional[str] = None
  34. class CustomEndpointUpdate(BaseModel):
  35. id: str = ""
  36. name: str
  37. base_url: str
  38. model: str
  39. api_key: Optional[str] = None
  40. # Same choices as the CLI's custom-provider setup; "" = auto-detect at runtime.
  41. # None (older UI payload) leaves a hand-written api_mode alone.
  42. api_mode: Optional[Literal["", "chat_completions", "codex_responses", "anthropic_messages"]] = None
  43. context_length: Optional[int] = None
  44. discover_models: bool = True
  45. make_default: bool = False
  46. models: Optional[list[str]] = None
  47. model_details: Optional[list[CustomEndpointModelDetail]] = None
  48. class MessagingPlatformUpdate(BaseModel):
  49. enabled: Optional[bool] = None
  50. env: dict[str, str] = {}
  51. clear_env: list[str] = []
  52. # Explicit body profile beats the switcher's query param (same as other scoped writes).
  53. profile: Optional[str] = None
  54. class TelegramOnboardingStart(BaseModel):
  55. bot_name: Optional[str] = None
  56. class TelegramOnboardingApply(BaseModel):
  57. allowed_user_ids: list[str]
  58. profile: Optional[str] = None
  59. class WhatsAppOnboardingStart(BaseModel):
  60. mode: Optional[str] = "bot"
  61. allowed_users: Optional[str] = ""
  62. profile: Optional[str] = None
  63. reset_session: bool = False
  64. class WhatsAppOnboardingApply(BaseModel):
  65. mode: Optional[str] = None
  66. allowed_users: Optional[str] = None
  67. profile: Optional[str] = None
  68. class AudioTranscriptionRequest(BaseModel):
  69. data_url: str
  70. mime_type: Optional[str] = None
  71. class ManagedFileUpload(BaseModel):
  72. path: str
  73. data_url: str
  74. overwrite: bool = True
  75. class ChatImageUpload(BaseModel):
  76. data_url: str
  77. filename: Optional[str] = None
  78. class ManagedDirectoryCreate(BaseModel):
  79. path: str
  80. class ManagedFileDelete(BaseModel):
  81. path: str
  82. recursive: bool = False
  83. class FileTicketRequest(BaseModel):
  84. """POST /api/files/ticket — the exact query the ticketed download/stream URL carries."""
  85. route: Literal["download", "stream"]
  86. path: str
  87. profile: Optional[str] = None
  88. session_id: Optional[str] = None
  89. class ModelAssignment(BaseModel):
  90. """POST /api/model/set — assign a provider/model to a slot.
  91. scope="main" → model.provider + model.default; scope="auxiliary" → auxiliary.<task>.*
  92. (task="" = every auxiliary slot, task="__reset__" = reset every slot to provider="auto").
  93. """
  94. scope: str
  95. provider: str
  96. model: str
  97. task: str = ""
  98. # Auxiliary only. Omitted → the task's override is left alone; explicit null → cleared
  99. # (inherit the main agent's effort); a level → set. ``model_fields_set`` tells the two apart.
  100. reasoning_effort: Optional[str] = None
  101. # Custom/local endpoint URL + key, honored on main AND auxiliary slots: the runtime resolvers
  102. # read model.base_url / auxiliary.<task>.base_url (+ .api_key) and ignore OPENAI_BASE_URL.
  103. base_url: str = ""
  104. api_key: str = ""
  105. confirm_expensive_model: bool = False
  106. profile: Optional[str] = None
  107. class MoaModelSlot(BaseModel):
  108. provider: str = ""
  109. model: str = ""
  110. # Declared so a GET round-trip doesn't strip and wipe it.
  111. reasoning_effort: Optional[str] = None
  112. enabled: bool = True
  113. class _MoaReferenceControls(BaseModel):
  114. # None = no per-preset override; inherits auxiliary.moa_reference.timeout (900s default).
  115. reference_timeout: Optional[float] = None
  116. degraded_reference_policy: Literal["loud", "silent"] = "loud"
  117. @field_validator("reference_timeout", mode="before")
  118. @classmethod
  119. def _validate_reference_timeout(cls, value: Any) -> Optional[float]:
  120. """Reject JSON booleans/non-finite values before float coercion."""
  121. if value is None or value == "":
  122. return None
  123. try:
  124. timeout = float(value) if not isinstance(value, bool) else math.nan
  125. except (TypeError, ValueError) as exc:
  126. raise ValueError("reference_timeout must be a finite positive number") from exc
  127. if not math.isfinite(timeout) or timeout <= 0:
  128. raise ValueError("reference_timeout must be a finite positive number")
  129. return timeout
  130. class MoaPresetPayload(_MoaReferenceControls):
  131. reference_models: list[MoaModelSlot] = []
  132. aggregator: MoaModelSlot = MoaModelSlot()
  133. # None = temperature omitted from API calls (provider default), as for single-model agents.
  134. reference_temperature: Optional[float] = None
  135. aggregator_temperature: Optional[float] = None
  136. # Newer per-preset knobs (moa_config._normalize_preset): optional for older clients,
  137. # declared so GET round-trips don't erase them.
  138. fanout: Optional[str] = None
  139. enabled: bool = True
  140. class MoaConfigPayload(_MoaReferenceControls):
  141. default_preset: str = "default"
  142. active_preset: str = ""
  143. presets: dict[str, MoaPresetPayload] = {}
  144. # Backward-compatible flat payload fields for older dashboard/desktop clients.
  145. reference_models: list[MoaModelSlot] = []
  146. aggregator: MoaModelSlot = MoaModelSlot()
  147. reference_temperature: Optional[float] = None
  148. aggregator_temperature: Optional[float] = None
  149. fanout: Optional[str] = None
  150. enabled: bool = True
  151. profile: Optional[str] = None
  152. class FsWriteText(BaseModel):
  153. path: str
  154. content: str
  155. #: The session the file was read for: its /workspace is that session's sandbox.
  156. session_id: Optional[str] = None
  157. class GitPathBody(BaseModel):
  158. path: str
  159. class GitFileBody(BaseModel):
  160. path: str
  161. file: Optional[str] = None
  162. class GitPrListBody(BaseModel):
  163. path: str
  164. branches: list[str] = []
  165. # PRs a session recovered from its transcript — known by number, not branch.
  166. numbers: list[int] = []
  167. class SessionPrScanBody(BaseModel):
  168. ids: list[str] = []
  169. class GitCommitBody(BaseModel):
  170. path: str
  171. message: str
  172. push: bool = False
  173. class GitWorktreeAddBody(BaseModel):
  174. path: str
  175. name: Optional[str] = None
  176. branch: Optional[str] = None
  177. base: Optional[str] = None
  178. existingBranch: Optional[str] = None
  179. class GitWorktreeRemoveBody(BaseModel):
  180. path: str
  181. worktreePath: str
  182. force: bool = False
  183. class GitBranchSwitchBody(BaseModel):
  184. path: str
  185. branch: str
  186. class CuratorPause(BaseModel):
  187. paused: bool
  188. class LearningNodeRef(BaseModel):
  189. id: str
  190. profile: Optional[str] = None
  191. class LearningNodeEdit(BaseModel):
  192. id: str
  193. content: str
  194. profile: Optional[str] = None
  195. class DebugShareRequest(BaseModel):
  196. # Redaction scrubs credential-shaped tokens before logs leave the machine; opt-out only.
  197. redact: bool = True
  198. lines: int = 200 # recent log lines in the summary tail (full logs are separate)
  199. class TTSSpeakRequest(BaseModel):
  200. text: str
  201. class VoiceLiveSessionRequest(BaseModel):
  202. """POST /api/audio/voice-live/session: the renderer's WebRTC SDP offer plus optional prior
  203. text turns (``{"type":"message","role":..,"content":[..]}``) to seed the live voice model."""
  204. sdp: str
  205. history: Optional[list[dict[str, Any]]] = None
  206. class TTSLeaseRequest(BaseModel):
  207. """POST /api/audio/tts-lease: ``lease`` names the toggle/surface holding the lease
  208. (``desktop:read-aloud``, ``desktop:conversation``); ``active`` True acquires + warms, False releases."""
  209. lease: str
  210. active: bool = True
  211. class STTLeaseRequest(BaseModel):
  212. """POST /api/audio/stt-lease: ``lease`` names the voice-input session holding the lease
  213. (``desktop:voice-input:<renderer>``); ``active`` True acquires + pre-loads the local
  214. STT model, False releases. Unlike TTS, release never unloads (shared engine)."""
  215. lease: str
  216. active: bool = True
  217. class OAuthSubmitBody(BaseModel):
  218. session_id: str
  219. code: str
  220. class BulkDeleteSessions(BaseModel):
  221. ids: list[str]
  222. profile: Optional[str] = None
  223. class SessionImport(BaseModel):
  224. request_id: Optional[str] = None
  225. expected_revision: Optional[StrictInt] = Field(None, ge=0)
  226. sessions: list[dict[str, Any]]
  227. profile: Optional[str] = None
  228. class SessionRename(BaseModel):
  229. request_id: Optional[str] = None
  230. expected_revision: Optional[StrictInt] = Field(None, ge=0)
  231. expected_generation: Optional[StrictInt] = Field(None, ge=0)
  232. title: Optional[str] = None
  233. archived: Optional[StrictBool] = None
  234. hidden: Optional[StrictBool] = None # also used by cross-profile reconciliation
  235. pinned: Optional[StrictBool] = None # durable "keep" (Desktop pins); exempt from auto_archive
  236. # Read-state watermark (sessions.last_read_at): True = unread, False = read now, None = leave.
  237. unread: Optional[StrictBool] = None
  238. profile: Optional[str] = None # session owned by another profile (opens its state.db)
  239. class SessionOwnerBackfill(BaseModel):
  240. """POST /api/sessions/owner-backfill (legacy migration). ``profile`` scopes WHICH state.db is
  241. stamped; the stamped value is always that store's own serving-profile identity — the caller
  242. cannot inject an arbitrary owner."""
  243. profile: Optional[str] = None
  244. class SessionPrune(BaseModel):
  245. older_than_days: Optional[float] = 90
  246. source: Optional[str] = None
  247. profile: Optional[str] = None
  248. # Extended filters (all optional, ANDed — mirrors the CLI flags); *_before/after = epoch s
  249. started_before: Optional[float] = None
  250. started_after: Optional[float] = None
  251. title_like: Optional[str] = None
  252. end_reason: Optional[str] = None
  253. cwd_prefix: Optional[str] = None
  254. min_messages: Optional[int] = None
  255. max_messages: Optional[int] = None
  256. model_like: Optional[str] = None
  257. provider: Optional[str] = None
  258. user_id: Optional[str] = None
  259. chat_id: Optional[str] = None
  260. chat_type: Optional[str] = None
  261. branch_like: Optional[str] = None
  262. min_tokens: Optional[int] = None
  263. max_tokens: Optional[int] = None
  264. min_cost: Optional[float] = None
  265. max_cost: Optional[float] = None
  266. min_tool_calls: Optional[int] = None
  267. max_tool_calls: Optional[int] = None
  268. include_archived: bool = False
  269. dry_run: bool = False
  270. class CronJobCreate(BaseModel):
  271. paused: StrictBool = False
  272. paused_reason: Optional[str] = None
  273. prompt: str = ""
  274. schedule: str
  275. name: str = ""
  276. deliver: str = "local"
  277. # Finite repeat count (runs N times then completes); None = unlimited. Accepts the
  278. # same user-facing strings the CLI accepts ('forever'/'once'/'3'). Normalization and
  279. # validation happen in cron.jobs.create_job via normalize_repeat_value — the shared
  280. # chokepoint with the CLI and update paths — so an unparseable value 400s there.
  281. repeat: Optional[int | str] = None
  282. skills: Optional[list[str]] = None
  283. model: Optional[str] = None
  284. provider: Optional[str] = None
  285. base_url: Optional[str] = None
  286. script: Optional[str] = None
  287. context_from: Optional[Any] = None
  288. enabled_toolsets: Optional[list[str]] = None
  289. workdir: Optional[str] = None
  290. no_agent: bool = False
  291. # Validated in cron.jobs.create_job (unknown IANA zone / out-of-range grace -> 400).
  292. timezone: Optional[str] = None
  293. grace_minutes: Optional[int | str] = None
  294. # Missed-run policy: true runs one catch-up, false skips; omitted follows the default.
  295. catch_up: Optional[StrictBool] = None
  296. class CronJobUpdate(BaseModel):
  297. updates: dict
  298. class AutomationBlueprintInstantiate(BaseModel):
  299. blueprint: str # blueprint key, e.g. "morning-brief"
  300. values: dict[str, Any] = {} # filled slot values from the form
  301. class MCPServerCreate(BaseModel):
  302. name: str
  303. url: Optional[str] = None
  304. command: Optional[str] = None
  305. args: list[str] = []
  306. env: dict[str, str] = {} # KEY=VALUE for stdio servers (API keys, etc.)
  307. auth: Optional[str] = None # "none" | "oauth" | "header" | None
  308. # One-time provisioning input; persisted only to the profile's .env.
  309. bearer_token: Optional[SecretStr] = None
  310. profile: Optional[str] = None
  311. class MCPServersReplace(BaseModel):
  312. # Whole-map replace (name → raw config) for the GUI mcp.json editor.
  313. servers: dict[str, dict[str, Any]] = {}
  314. profile: Optional[str] = None
  315. class MCPEnabledToggle(BaseModel):
  316. enabled: bool
  317. profile: Optional[str] = None
  318. class MCPCatalogInstall(BaseModel):
  319. name: str
  320. env: dict[str, str] = {} # KEY=VALUE for entries declaring required env vars
  321. enable: bool = True
  322. profile: Optional[str] = None
  323. class PairingApprove(BaseModel):
  324. platform: str
  325. code: str = ""
  326. request_id: str = ""
  327. profile: Optional[str] = None
  328. class PairingRevoke(BaseModel):
  329. platform: str
  330. user_id: str
  331. profile: Optional[str] = None
  332. class WebhookCreate(BaseModel):
  333. name: str
  334. description: Optional[str] = None
  335. events: list[str] = []
  336. prompt: Optional[str] = None
  337. script: Optional[str] = None
  338. skills: list[str] = []
  339. deliver: str = "log"
  340. deliver_only: bool = False
  341. deliver_chat_id: Optional[str] = None
  342. secret: Optional[str] = None # omit to auto-generate
  343. class WebhookEnabledToggle(BaseModel):
  344. enabled: bool
  345. class CredentialPoolAdd(BaseModel):
  346. provider: str
  347. api_key: str # OAuth pooling stays CLI-only (needs an interactive browser flow)
  348. label: Optional[str] = None
  349. class MemoryProviderSelect(BaseModel):
  350. provider: str # "" or "built-in" disables the external provider
  351. class MemoryReset(BaseModel):
  352. target: str = "all" # "all" | "memory" | "user"
  353. class BackupRequest(BaseModel):
  354. output: Optional[str] = None # defaults to a timestamped zip in the home dir
  355. class ImportRequest(BaseModel):
  356. archive: str
  357. # --force: the spawned `hermes import` has stdin=DEVNULL, so its "Continue? [y/N]" prompt would
  358. # hit EOF and abort; the dashboard confirms in its own modal.
  359. force: bool = False
  360. class HookCreate(BaseModel):
  361. event: str
  362. command: str
  363. matcher: Optional[str] = None
  364. timeout: Optional[int] = None
  365. # Also write the consent allowlist entry; without it the hook won't fire until approved.
  366. approve: bool = True
  367. class HookDelete(BaseModel):
  368. event: str
  369. command: str
  370. class SkillInstallRequest(BaseModel):
  371. identifier: str
  372. profile: Optional[str] = None
  373. class SkillUninstallRequest(BaseModel):
  374. name: str
  375. profile: Optional[str] = None
  376. class SkillsUpdateRequest(BaseModel):
  377. profile: Optional[str] = None
  378. class ProfileCreate(BaseModel):
  379. name: str
  380. soul: Optional[str] = None
  381. clone_from: Optional[str] = None
  382. clone_from_default: bool = False # legacy clients; new ones send clone_from explicitly
  383. clone_all: bool = False
  384. # Opt-in: also copy the source's messaging channels (bot tokens, allowlists, platform sections).
  385. # Default False — a copied bot credential makes two profiles collide over one bot.
  386. clone_channels: bool = False
  387. no_skills: bool = False
  388. description: Optional[str] = None
  389. provider: Optional[str] = None
  390. model: Optional[str] = None
  391. # Profile-builder additions, applied best-effort AFTER the profile dir exists (a hiccup never 500s).
  392. mcp_servers: list[MCPServerCreate] = []
  393. keep_skills: list[str] = [] # skills to KEEP: non-empty = replace semantics (unlisted seeded ones disabled)
  394. # Installed async via `hermes -p <name> skills install` (skills_hub.SKILLS_DIR is import-time-bound,
  395. # so HERMES_HOME can't redirect it); PIDs go back for the UI to poll.
  396. hub_skills: list[str] = []
  397. class ProfileRename(BaseModel):
  398. new_name: str
  399. class ProfileExport(BaseModel):
  400. extra_files: dict[str, str] = {} # extra root-level files, filename → text
  401. output: str = "" # archive path; empty → a staging path under HERMES_HOME
  402. class ProfileImport(BaseModel):
  403. archive: str # profile .tar.gz on the backend's filesystem
  404. name: Optional[str] = None # overrides the name inferred from the archive root
  405. class ProfileSoulUpdate(BaseModel):
  406. content: str
  407. class ProfileActiveUpdate(BaseModel):
  408. name: str
  409. class ProfileDescriptionUpdate(BaseModel):
  410. description: str = ""
  411. class ProfileModelUpdate(BaseModel):
  412. provider: str
  413. model: str
  414. class ProfileDescribeAuto(BaseModel):
  415. overwrite: bool = False
  416. class SkillToggle(BaseModel):
  417. name: str
  418. enabled: bool
  419. profile: Optional[str] = None
  420. class SkillLock(BaseModel):
  421. name: str
  422. locked: bool
  423. profile: Optional[str] = None
  424. class SkillCreate(BaseModel):
  425. name: str
  426. content: str
  427. category: Optional[str] = None
  428. profile: Optional[str] = None
  429. class SkillContentUpdate(BaseModel):
  430. name: str
  431. content: str
  432. profile: Optional[str] = None
  433. class ToolsetToggle(BaseModel):
  434. enabled: bool
  435. profile: Optional[str] = None
  436. class ToolsetProviderSelect(BaseModel):
  437. provider: str
  438. # Web-only scope 'search' | 'extract'; omitted → whole-provider (legacy web.backend path).
  439. capability: Optional[str] = None
  440. profile: Optional[str] = None
  441. class ToolsetModelSelect(BaseModel):
  442. model: str
  443. provider: Optional[str] = None
  444. profile: Optional[str] = None
  445. class ToolsetEnvUpdate(BaseModel):
  446. env: dict[str, str]
  447. profile: Optional[str] = None
  448. class ToolsetPostSetup(BaseModel):
  449. key: str
  450. profile: Optional[str] = None
  451. class TerminalBackendSelect(BaseModel):
  452. backend: str
  453. profile: Optional[str] = None
  454. class DelegationBackendSelect(BaseModel):
  455. backend: str
  456. profile: Optional[str] = None
  457. class DelegationModelMapUpdate(BaseModel):
  458. options: list[dict[str, Any]]
  459. default: Optional[str] = None
  460. profile: Optional[str] = None
  461. class DelegationProfileRoutesUpdate(BaseModel):
  462. profiles: list[dict[str, Any]]
  463. default: Optional[str] = None
  464. profile: Optional[str] = None
  465. class RawConfigUpdate(BaseModel):
  466. yaml_text: str
  467. profile: Optional[str] = None
  468. class ThemeSetBody(BaseModel):
  469. name: str
  470. class FontSetBody(BaseModel):
  471. font: str
  472. class _AgentPluginInstallBody(BaseModel):
  473. identifier: str
  474. force: bool = False
  475. enable: bool = True
  476. # Install by curated-catalog name (resolves repo + pinned SHA server-side).
  477. catalog_name: Optional[str] = None
  478. # Pin a custom source to one full 40-hex commit SHA (same contract as ``--ref``).
  479. ref: Optional[str] = None
  480. class _PluginProvidersPutBody(BaseModel):
  481. memory_provider: Optional[str] = None
  482. context_engine: Optional[str] = None
  483. class _PluginVisibilityBody(BaseModel):
  484. hidden: bool
  485. class _PluginAutoUpdateBody(BaseModel):
  486. enabled: bool