systemprompt-files

Files that stay on your infrastructure, with a record of every one. Governed uploads with MIME validation, AI-generated image tracking, and content associations, stored where you control them and audited like every other operation.

Layer: Domain — business-logic modules that implement systemprompt.io features. Part of the systemprompt-core workspace.

Overview

Infrastructure · Self-Hosted Deployment

This crate provides file storage, metadata management, and content-file linking capabilities. It handles file uploads with validation, AI-generated image tracking, and content associations.

Usage

[dependencies]
systemprompt-files = "0.21"

Configured via files.yaml:

files:
  urlPrefix: "/files"
  upload:
    enabled: true
    maxFileSizeBytes: 52428800
    persistenceMode: context_scoped
    allowedTypes:
      images: true
      documents: true
      audio: true
      video: false

Module Layout

Module	Purpose
`models/`	`File` entity, `content_file` junction with `FileRole`, and file/image metadata types.
`repository/`	Compile-time-verified persistence for files, content linking, and AI-image queries.
`services/`	`FileUploadService` (validation, storage, persistence) and the AI-persistence provider.
`config/`	`FilesConfig` YAML loading, upload limits, allowed types, and profile-driven validation.
`jobs/`	`FileIngestionJob` scanning storage for images.

Modules

Module	Purpose
`config`	Profile-driven configuration loading, validation, and persistence modes
`error`	`FilesError` and `FilesResult` shared across the crate
`extension`	`FilesExtension` registering schemas and jobs via the extension framework
`jobs`	Background file ingestion with inventory registration
`models`	Data structures: `File`, `ContentFile`, `FileRole`, metadata variants
`repository`	Database access layer using compile-time verified `sqlx` macros
`services`	Upload, validation, and AI-persistence service wrappers

Public Types

Type	Description
`File`	File entity with path, URL, metadata, and typed identifiers
`ContentFile`	Links a file to content with role and display order
`FileRole`	Featured, Attachment, Inline, OgImage, Thumbnail
`FileMetadata`	Container for checksums and type-specific metadata
`TypeSpecificMetadata`	Enum variant carrying image, audio, document, or video metadata
`ImageMetadata` / `ImageGenerationInfo`	Image dimensions, alt text, and AI generation provenance
`AudioMetadata` / `DocumentMetadata` / `VideoMetadata`	Type-specific metadata records
`FileChecksums`	SHA-256 / content checksum container
`FileUploadRequest` / `FileUploadRequestBuilder`	Builder for upload operations
`UploadedFile`	Result returned by `FileUploadService`
`FileCategory` / `FileValidator`	Upload validation surface
`FilesConfig` / `FilesConfigYaml` / `FilesConfigValidator`	Configuration types and validation
`FileUploadConfig` / `AllowedFileTypes` / `FilePersistenceMode`	Upload policy configuration
`InsertFileRequest` / `FileRepository` / `FileStats`	Repository surface
`FilesAiPersistenceProvider`	Provider implementation for AI-generated image persistence
`FilesExtension`	Extension entry point registered via `inventory`
`FileIngestionJob`	Scheduled job that reconciles storage with database rows
`FilesError` / `FilesResult`	Crate-level error type and result alias

Jobs

Job	Description
`FileIngestionJob`	Scans the configured storage root and reconciles on-disk image files with database rows

Schemas

File	Purpose
`schema/files.sql`	Core `files` table definition
`schema/content_files.sql`	Junction table linking files to content
`schema/ai_image_analytics.sql`	View/table for AI-generated image analytics

Dependencies

Crate	Purpose
`systemprompt-database`	`DbPool` and `sqlx` query macros
`systemprompt-identifiers`	`FileId`, `UserId`, `ContentId`, `SessionId`, `TraceId`, `ContextId`
`systemprompt-traits`	`Job` trait for background jobs
`systemprompt-models`	`AppPaths`, `ProfileBootstrap`, shared models
`systemprompt-cloud`	Storage path constants and cloud integration
`systemprompt-config`	Profile and YAML configuration loading
`systemprompt-extension`	Extension trait and registration macros
`systemprompt-provider-contracts`	Provider trait contracts implemented by this crate
`systemprompt-logging`	Structured `tracing` integration

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

Domain layer · Own how your organization uses AI.

systemprompt-files 0.21.1

Production infrastructure for AI agents