Package org.machanism.machai.process.manager

package org.machanism.machai.process.manager
Provides provider factories and process-local token-usage reporting for generative-AI integrations.

This package separates application configuration from provider implementations. ProcessProviderManager parses a Provider:Model expression, resolves a provider implementation, creates it with a public no-argument constructor, and initializes it with a Configurator. The resulting object implements either ProcessProvider or EmbeddingProvider.

Provider creation

Call ProcessProviderManager.getProvider(String, org.machanism.macha.core.commons.configurator.Configurator) for process providers and ProcessProviderManager.getEmbeddingProvider(String, org.machanism.macha.core.commons.configurator.Configurator) for embedding providers. Each method passes the text following the first colon as the model name and returns null when the provider segment is blank. Process-provider names must be valid Java identifiers. Simple names are searched in the package conventions supported by the manager, followed by its nested-provider fallback. For embeddings, a provider segment containing a dot is used as a fully qualified class name; otherwise the same conventions are used. The resolved embedding class must implement EmbeddingProvider.

Provider implementations must expose a public no-argument constructor. Invalid names, missing classes, incompatible embedding classes, and reflective construction failures are reported as IllegalArgumentException. A runtime exception thrown by an embedding provider during initialization is propagated unchanged.

Usage reporting

Usage is an immutable record of input, cached-input, and output token counts for one interaction. UsageStatistics stores these records in a static, in-memory map keyed by the exact model identifier passed to addUsage(String, Usage). The registry is not persisted between application runs. Model-specific additions and reads are synchronized; logging writes summaries through the class's SLF4J logger. getUsageForModel(String) returns a defensive list copy, while getAllModelUsages() returns a shallow map copy whose value lists remain shared.

Example


 UsageStatistics.init();
 Configurator conf = ...;
 ProcessProvider chat = ProcessProviderManager.getProvider("OpenAI:gpt-4o", conf);
 EmbeddingProvider embeddings = ProcessProviderManager.getEmbeddingProvider(
         "OpenAI:text-embedding-3-small", conf);
 UsageStatistics.addUsage("OpenAI:gpt-4o", new Usage(500, 100, 200));
 UsageStatistics.logUsage();

Call init() during startup if eager utility-class initialization is desired. Use logUsage() to report every currently registered model or logUsageForModel(String) to report one model.

See Also:
  • Classes
    Class
    Description
    ProcessProviderManager
    Utility class for dynamically loading and initializing generative AI providers and embedding providers.
    Usage
    Immutable token-usage metrics for a single generative AI interaction.
    UsageStatistics
    Central registry for aggregated GenAI token-usage statistics.