mini_chat_sdk/
plugin_api.rs

1use async_trait::async_trait;
2use uuid::Uuid;
3
4use crate::audit_models::{
5    TurnAuditEvent, TurnDeleteAuditEvent, TurnEditAuditEvent, TurnRetryAuditEvent,
6};
7use crate::error::{MiniChatAuditPluginError, MiniChatModelPolicyPluginError, PublishError};
8use crate::models::{PolicySnapshot, PolicyVersionInfo, UsageEvent, UserLimits};
9
10/// Plugin API trait for mini-chat model policy implementations.
11///
12/// Plugins implement this trait to provide model catalog and policy data.
13/// The mini-chat module discovers plugins via GTS types-registry and
14/// delegates policy queries to the selected plugin.
15#[async_trait]
16pub trait MiniChatModelPolicyPluginClientV1: Send + Sync {
17    /// Get the current policy version for a user.
18    async fn get_current_policy_version(
19        &self,
20        user_id: Uuid,
21    ) -> Result<PolicyVersionInfo, MiniChatModelPolicyPluginError>;
22
23    /// Get the full policy snapshot for a given version, including
24    /// model catalog and kill switches.
25    async fn get_policy_snapshot(
26        &self,
27        user_id: Uuid,
28        policy_version: u64,
29    ) -> Result<PolicySnapshot, MiniChatModelPolicyPluginError>;
30
31    /// Get per-user credit limits for a specific policy version.
32    async fn get_user_limits(
33        &self,
34        user_id: Uuid,
35        policy_version: u64,
36    ) -> Result<UserLimits, MiniChatModelPolicyPluginError>;
37
38    /// Publish a usage event after turn finalization.
39    ///
40    /// Called by the outbox processor after the finalization transaction
41    /// commits. Plugins can forward the event to external billing systems.
42    async fn publish_usage(&self, payload: UsageEvent) -> Result<(), PublishError>;
43}
44
45/// Plugin API trait for mini-chat audit event publishing.
46///
47/// Plugins implement this trait to receive audit events from the mini-chat
48/// module. The mini-chat module discovers plugins via GTS types-registry and
49/// dispatches audit events to all registered implementations.
50///
51/// # Caller contract
52///
53/// The **caller** (mini-chat domain service) MUST redact secret patterns and
54/// truncate string content (max 8 KiB per field) *before* invoking any method
55/// on this trait. Plugins MUST assume all content fields are already sanitized.
56/// See DESIGN.md "Audit content handling (P1)" for the full redaction rule table.
57///
58/// # Delivery semantics
59///
60/// Audit emission is best-effort (fire-and-forget after DB commit). There is no
61/// transactional outbox for audit events. If the process crashes between DB
62/// commit and audit emission, the event is lost. Callers SHOULD track emission
63/// outcomes via `mini_chat_audit_emit_total{result}` metrics.
64///
65/// # Independence
66///
67/// When multiple audit plugin instances are registered, each MUST be
68/// independent. A failure in one plugin MUST NOT prevent delivery to others.
69#[async_trait]
70pub trait MiniChatAuditPluginClientV1: Send + Sync {
71    /// Emit a turn audit event (turn completed or failed).
72    async fn emit_turn_audit(&self, event: TurnAuditEvent) -> Result<(), MiniChatAuditPluginError>;
73
74    /// Emit a turn-retry audit event.
75    async fn emit_turn_retry_audit(
76        &self,
77        event: TurnRetryAuditEvent,
78    ) -> Result<(), MiniChatAuditPluginError>;
79
80    /// Emit a turn-edit audit event.
81    async fn emit_turn_edit_audit(
82        &self,
83        event: TurnEditAuditEvent,
84    ) -> Result<(), MiniChatAuditPluginError>;
85
86    /// Emit a turn-delete audit event.
87    async fn emit_turn_delete_audit(
88        &self,
89        event: TurnDeleteAuditEvent,
90    ) -> Result<(), MiniChatAuditPluginError>;
91}
mini_chat_sdk/plugin_api.rs

mini_chat_sdk/
plugin_api.rs
