Crate kizzasi

Expand description

§Kizzasi (兆候)

Autoregressive General-Purpose Signal Predictor (AGSP)

“Predicting the flux of the world with the precision of logic.”

Kizzasi is a Rust-native AGSP designed for continuous signal streams—audio, sensor data, robotics control signals, and video frames. Unlike traditional LLMs that operate on discrete text tokens, Kizzasi is built for the continuous domain.

§Core Innovation: Neuro-Symbolic Architecture

Kizzasi combines the learning capability of State Space Models (Mamba/RWKV) with the strict reliability of TensorLogic. This ensures that predicted signals not only follow statistical likelihoods but also adhere to defined physical laws, safety constraints, and logical rules.

§COOLJAPAN Ecosystem

This crate is part of the COOLJAPAN scientific computing ecosystem and follows the KIZZASI_POLICY.md for dependency management, using:

scirs2-core for array and numerical operations
tensorlogic for constraint logic

§Quick Start

use kizzasi::prelude::*;

fn main() -> Result<()> {
    // Initialize predictor with Mamba2 backend
    let config = KizzasiConfig::new()
        .model_type(ModelType::Mamba2)
        .context_window(8192);

    let mut predictor = Kizzasi::new(config)?;

    // Single step prediction
    let input = array![0.1, 0.2, 0.3];
    let output = predictor.step(&input)?;

    Ok(())
}

§Common Use Cases

§Audio Processing

let mut predictor = KizzasiBuilder::audio_preset().build()?;
let sample = array![0.5]; // Single sample
let next = predictor.step(&sample)?;

§Robotics Control

let mut predictor = KizzasiBuilder::robotics_preset(6).build()?; // 6-DOF
let joint_angles = array![0.1, 0.2, 0.3, 0.4, 0.5, 0.6];
let predicted = predictor.step(&joint_angles)?;

§Sensor Monitoring

let mut predictor = KizzasiBuilder::sensor_preset(10).build()?;
let readings = array![/* 10 sensor values */];
let forecast = predictor.predict_n(&readings, 5)?; // 5 steps ahead

§With Safety Constraints

use kizzasi::{ConstraintBuilder, Guardrail, GuardrailSet};

let mut predictor = KizzasiBuilder::robotics_preset(3).build()?;

// Add safety bounds
let mut guardrails = GuardrailSet::new();
let constraint = ConstraintBuilder::new()
    .name("joint_limits")
    .greater_eq(-3.14)
    .less_eq(3.14)
    .build()?;
guardrails.add_global(Guardrail::new(constraint, false));
predictor.set_guardrails(guardrails);

§Features

std (default): Standard library support
full (default): Enable all features (io, logic, async, config-files, macros)
io: Physical world connectors (MQTT, Audio)
logic: TensorLogic constraint enforcement
async: Async/streaming APIs, connection pooling with tokio
config-files: TOML/YAML configuration file support
macros: Derive macros for custom configurations

§Performance

Kizzasi is optimized for real-time inference:

Zero-copy operations where possible
Efficient state management
SIMD-optimized computations via scirs2-core
Batch processing support

Run benchmarks with: cargo bench --bench predictor_benchmarks

§Thread Safety

Kizzasi predictors are Send but not Sync. For concurrent predictions:

Use fork() to create independent predictors per thread
Or wrap in Arc<Mutex<Kizzasi>> for shared access
Async APIs are available with the async feature

§Advanced Features

§Model Versioning and A/B Testing

Manage multiple model versions with deployment strategies:

use kizzasi::versioning::{ModelRegistry, DeploymentStrategy};

let mut registry = ModelRegistry::new();
registry.deploy("2.0.0", DeploymentStrategy::Canary { traffic_percent: 10 })?;
let model = registry.select_for_request(request_id)?;

§Telemetry and Metrics

Production-grade metrics collection and monitoring:

use kizzasi::telemetry::{MetricsCollector, MetricEvent};

let metrics = MetricsCollector::new("my_service");
metrics.record(MetricEvent::Prediction { latency_us: 1500, input_dim: 64, output_dim: 64 });
let stats = metrics.snapshot();
println!("P99 latency: {:.2}ms", stats.p99_latency_ms);

§Connection Pooling

Efficient resource management for I/O operations (requires async feature):

use kizzasi::pool::{ConnectionPool, PoolConfig};

let config = PoolConfig::default().with_max_connections(10);
let pool = ConnectionPool::new(factory, config).await?;
let conn = pool.acquire().await?;

§Examples

See the examples/ directory for comprehensive examples:

basic_prediction - Core API usage
with_guardrails - Constraint enforcement
audio_processing - Audio signal prediction
robotics_control - Robot control systems
streaming - Async streaming APIs
anomaly_detection - Real-time anomaly detection
model_checkpointing - Save/load predictor configuration
custom_model - Advanced configuration patterns
production_deployment - Full production setup with versioning, metrics, and pooling
metrics_monitoring - Comprehensive metrics and monitoring

Re-exports§

pub use autotuning::AdaptiveTuner;
pub use autotuning::AutoTuner;
pub use autotuning::TuningConfig;
pub use autotuning::TuningRecommendation;
pub use autotuning::WorkloadProfile;
pub use ensemble::EnsemblePredictor;
pub use ensemble::EnsembleStats;
pub use ensemble::ModelStats;
pub use ensemble::VotingStrategy;
pub use optimization::CacheStats;
pub use optimization::OptimizationConfig;
pub use optimization::OptimizationStats;
pub use optimization::OptimizedPredictor;
pub use plugin::LoggingPlugin;
pub use plugin::Plugin;
pub use plugin::PluginContext;
pub use plugin::PluginManager;
pub use plugin::PluginPhase;
pub use plugin::StatsPlugin;
pub use telemetry::Instrumented;
pub use telemetry::MetricEvent;
pub use telemetry::MetricValue;
pub use telemetry::MetricsCollector;
pub use telemetry::MetricsConfig;
pub use telemetry::MetricsSnapshot;
pub use versioning::DeploymentStrategy;
pub use versioning::ModelMetadata;
pub use versioning::ModelRegistry;
pub use versioning::ModelVersion;
pub use versioning::RegistryStats;
pub use versioning::SemanticVersion;
pub use pool::ConnectionFactory;
pub use pool::ConnectionPool;
pub use pool::PoolConfig;
pub use pool::PoolStats;
pub use distributed::DistributedConfig;
pub use distributed::DistributedPredictor;
pub use distributed::LoadBalancingStrategy;
pub use distributed::WorkerStats;
pub use config::ConfigFile;
pub use config::ConfigFormat;
pub use config::ConfigLoader;

Modules§

autotuning: Automatic performance tuning and workload profiling
config: Configuration file loading support for TOML and YAML
distributed: Distributed prediction framework for Kizzasi
ensemble: Multi-model ensemble predictions with voting strategies
optimization: Advanced optimization system for high-performance predictions
plugin: Plugin system for extending Kizzasi functionality
pool: Connection pooling for efficient I/O resource management.
prelude: Prelude module for convenient imports
telemetry: Telemetry and metrics collection for production monitoring.
versioning: Model versioning and lifecycle management.

Macros§

array: Create an Array with one, two, three, four, five, or six dimensions.

Structs§

AsyncPredictor: Async predictor wrapper with channel-based I/O
AudioConfig: Configuration for audio I/O
AudioInput: Audio input stream
CheckpointMetadata: Metadata about the checkpoint
ConstrainedProjection: Projects predictions onto valid constraint manifolds
Constraint: A single constraint on signal values
ConstraintBuilder: Builder for constructing constraints
ContinuousEmbedding: Continuous embedding layer for signal values
FullStateCheckpoint: Full state checkpoint including all model weights and hidden state
Guardrail: A single guardrail combining a constraint with enforcement policy
GuardrailSet: A set of guardrails for multi-dimensional signals
HiddenState: Represents the hidden state of the SSM
Kizzasi: The main Kizzasi AGSP predictor
KizzasiBuilder: Builder for constructing Kizzasi predictors with a fluent API
KizzasiConfig: Configuration for the Kizzasi AGSP engine
LazyKizzasi: Lazy-initialized Kizzasi predictor
MemoryStream: In-memory signal stream for testing
MqttClient: MQTT client for receiving sensor data
MqttConfig: Configuration for MQTT connection
MqttStream: Synchronous wrapper for MqttClient as SignalStream
PredictionStream: Async signal stream that yields predictions
PredictorCheckpoint: Serializable representation of a Kizzasi predictor checkpoint
SelectiveSSM: Selective State Space Model (Mamba-style)
SignalInput: Wrapper type for signal inputs with ergonomic conversions
SignalProcessor: Signal processor for pre-processing sensor data
StreamConfig: Configuration for signal streams
StreamProcessor: Stream adapter for processing signal streams asynchronously

Enums§

BoundType: Type of bound constraint
ComposedConstraint: Composed constraint from multiple constraints with logical operators
CoreError: Errors that can occur in the core SSM engine
ErrorCategory: Error category for classification
Filter: Filter types for signal processing
IoError: Errors that can occur in the IO module
KizzasiError: Unified error type for Kizzasi with detailed context and recovery suggestions
LogicError: Errors that can occur in the logic module
LogicalOperator: Logical operators for combining constraints
ModelType: Type of state space model to use

Traits§

ConstrainedInference: Trait for constrained inference
SignalPredictor: Core trait for autoregressive signal prediction
SignalStream: Trait for signal streams
StateSpaceModel: Trait for state space model implementations

Type Aliases§

Array1: one-dimensional array
Array2: two-dimensional array
CoreResult: Result type alias for core operations
IoResult: Result type alias for IO operations
KizzasiResult: Result type alias for Kizzasi operations
LogicResult: Result type alias for logic operations

Derive Macros§

Instrumented: Derive macro for metrics instrumentation.
KizzasiConfig: Derive macro for custom Kizzasi configurations.
Preset: Derive macro for generating preset constructors.

Crate kizzasi

Crate kizzasi Copy item path

§Kizzasi (兆候)

§Core Innovation: Neuro-Symbolic Architecture

§COOLJAPAN Ecosystem

§Quick Start

§Common Use Cases

§Audio Processing

§Robotics Control

§Sensor Monitoring

§With Safety Constraints

§Features

§Performance

§Thread Safety

§Advanced Features

§Model Versioning and A/B Testing

§Telemetry and Metrics

§Connection Pooling

§Examples

Re-exports§

Modules§

Macros§

Structs§

Enums§

Traits§

Type Aliases§

Derive Macros§

Crate kizzasi