agpu/ontology/mod.rs
1//! # Ontology — Agent Discoverability System
2//!
3//! Provides structured metadata for every component in an agpu application.
4//! AI agents can introspect widget schemas, discover available actions,
5//! query capabilities, and navigate the UI tree programmatically.
6
7mod action;
8mod capability;
9pub mod gpu;
10pub mod registry;
11mod schema;
12
13pub use action::{ActionParam, ActionParamType, AgentAction};
14pub use capability::AgentCapability;
15pub use registry::{Accessibility, NodeBounds, OntologyRegistry, UiNode, UiTree};
16pub use schema::{PropertyConstraint, PropertySchema, PropertyType, SemanticRole, WidgetSchema};
17
18/// Trait for widgets that expose metadata to agents.
19///
20/// Any widget implementing this trait becomes discoverable: agents can introspect
21/// its schema, invoke actions, and read its state as structured data.
22pub trait Discoverable {
23 /// Returns the schema describing this widget type.
24 fn schema(&self) -> WidgetSchema;
25
26 /// Returns the capabilities of this specific widget instance.
27 fn capabilities(&self) -> Vec<AgentCapability>;
28
29 /// Returns the actions available on this specific widget instance.
30 fn actions(&self) -> Vec<AgentAction>;
31
32 /// Returns the semantic role of this widget.
33 fn semantic_role(&self) -> SemanticRole;
34
35 /// Returns the current state as a JSON value for agent inspection.
36 fn agent_state(&self) -> serde_json::Value;
37
38 /// Attempt to execute a named action with the given JSON parameters.
39 fn execute_action(
40 &mut self,
41 action: &str,
42 params: &serde_json::Value,
43 ) -> Result<serde_json::Value, String>;
44
45 /// An optional unique identifier for this widget instance in the UI tree.
46 fn agent_id(&self) -> Option<&str> {
47 None
48 }
49
50 /// An optional accessibility label for screen readers and agents.
51 fn accessibility_label(&self) -> Option<String> {
52 None
53 }
54}