systemprompt-traits 0.10.0

Trait-first interface contracts for systemprompt.io AI governance infrastructure. Repository, provider, and service abstractions shared across the MCP governance pipeline.
Documentation

Production infrastructure for AI agents

Website · Documentation · Guides · Core · Template · Discord

systemprompt-traits

Crates.io Docs.rs License: BSL-1.1

Trait-first interface contracts for the systemprompt.io platform. Defines the provider, repository, registry, and service abstractions that every other layer (infra, domain, app, entry) implements or consumes, plus the cross-cutting ExtensionError contract used to render domain errors over HTTP and MCP.

Layer: Shared. Part of the systemprompt-core workspace. Depends only on systemprompt-identifiers and systemprompt-provider-contracts.

Installation

[dependencies]
systemprompt-traits = "0.9"

Enable the web feature to pull in the axum-backed ApiModule trait:

[dependencies]
systemprompt-traits = { version = "0.9", features = ["web"] }

Example

use async_trait::async_trait;
use systemprompt_traits::Service;

struct HealthPinger;

#[async_trait]
impl Service for HealthPinger {
    fn name(&self) -> &str { "health-pinger" }
    async fn start(&mut self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> { Ok(()) }
    async fn stop(&mut self) -> Result<(), Box<dyn std::error::Error + Send + Sync>> { Ok(()) }
    async fn health_check(&self) -> Result<bool, Box<dyn std::error::Error + Send + Sync>> { Ok(true) }
}

Module map

Module Contents
ai_providers AiSessionProvider, AiFilePersistenceProvider, image-generation metadata, and storage config.
analytics AnalyticsProvider, FingerprintProvider, session inputs, and AnalyticsProviderError.
artifact ArtifactSupport and built-in artifact JSON-Schema helpers.
auth UserProvider, RoleProvider, AuthUser, and AuthProviderError.
content Content provider traits, ContentSummary, and ContentItem.
context AppContext, ConfigProvider, DatabaseHandle, ModuleRegistry, Module, ContextPropagation, and the optional ApiModule (web feature).
context_provider ContextProvider for conversation contexts and ContextWithStats.
domain_config DomainConfig and DomainConfigRegistry for per-domain config loading.
events Log, user, and analytics event publisher traits.
extension_error ExtensionError trait, ApiError, and McpErrorData wire types.
file_upload FileUploadProvider, FileUploadInput, and UploadedFileInfo.
jwt JwtValidationProvider, AgentJwtClaims, and GenerateTokenParams.
log_service Generic LogService persistence trait.
mcp_service McpServiceProvider and McpServerMetadata.
module register_module! macro for compile-time module registration via inventory.
process ProcessCleanupProvider for PID and port lifecycle.
registry AgentRegistryProvider, McpRegistryProvider, AgentInfo, and McpServerInfo.
repository RepositoryError enum shared by domain repositories.
scheduler JobStatus and scheduler error types.
service Service and AsyncService lifecycle traits.
session_analytics SessionAnalyticsProvider for session-scoped counters.
startup_events Startup event publisher traits and types.
storage FileStorage, StoredFileId, and StoredFileMetadata.
validation Validate, MetadataValidation, and the field-level ValidationError.
validation_report ValidationReport, StartupValidationReport, and warning types.

Provider traits re-exported from systemprompt-provider-contracts (chat, LLM, tools, jobs) are surfaced at the crate root so downstream callers do not need to depend on both crates.

Error model

Each provider trait pairs with a thiserror-derived error enum (e.g. AuthProviderError, JwtProviderError, FileStorageError, ProcessProviderError). The cross-cutting ExtensionError trait is implemented by downstream errors so the API and MCP transports can render them uniformly into ApiError (HTTP) or McpErrorData (MCP).

RepositoryError is the standard error type for repository implementations across domain crates and is #[non_exhaustive].

Async traits

Most provider traits are exposed as Arc<dyn TraitName> via the Dyn* aliases. Until trait dispatch supports native async fn on dyn traits, these continue to rely on #[async_trait]; each trait whose contract requires it is annotated with the rationale.

Feature flags

Feature Default Effect
web off Enables the ApiModule trait and pulls in axum for HTTP routing.

Dependencies

  • systemprompt-provider-contracts, systemprompt-identifiers — sibling shared-layer crates.
  • async-trait — async methods on dyn-compatible traits.
  • thiserror — error enum derives.
  • inventory — compile-time module registration.
  • serde, serde_json, chrono, uuid, futures, http, tracing, xxhash-rust.
  • axum (optional, web feature).

License

BSL-1.1 (Business Source License). Source-available for evaluation, testing, and non-production use. Production use requires a commercial license. Each version converts to Apache 2.0 four years after publication. See LICENSE.

systemprompt.io · Documentation · Guides · Live Demo · Template · crates.io · docs.rs · Discord

Shared layer · Own how your organization uses AI.