Package org.machanism.machai.process.provider

package org.machanism.machai.process.provider

Provider contracts, reusable lifecycle infrastructure, and local dispatch implementations for Machai process integrations.

The package separates provider-facing orchestration from provider-specific transport code. ProcessProvider defines the common lifecycle for initialization, instructions, prompts, tool and resource registration, execution, project-directory context, error handling, and state clearing. Implementations may retain conversation or request state between calls, so a caller should use ProcessProvider.clear() when beginning an independent request and should not assume that every implementation has the same execution semantics.

Provider contracts and decorators

• ProcessProvider is the primary abstraction for conversational or process-oriented providers. EmbeddingProvider is the separate contract for providers that turn text into embedding vectors.
• ProcessProviderAdapter is a delegating implementation useful for decorating a provider with application-level concerns such as logging, metrics, retries, or request shaping. Set its delegate before forwarding lifecycle calls.
• AbstractAIProvider supplies shared state and reflection-based registration for methods annotated with Tool, Prompt, and Resource. It also provides model, configuration, project-directory, instruction, token-limit, and tool-error handling state for concrete subclasses.

Included implementations

• NoneProvider is an intentional no-op provider. It accepts lifecycle input without retaining or processing it, returns null from NoneProvider.perform(), and always reports an immutable empty tool list. Initializing it with model "log" enables diagnostic INFO messages; other model values disable those messages.
• ToolsProvider is a lightweight local dispatcher. It stores prompts, keeps registered tools in registration order, and, when initialized with model "yaml", parses the most recently submitted prompt as a YAML mapping. The mapping must contain a tool name and may contain params; the named function is invoked, with non-string results serialized as JSON. A YAML execution requires at least one prompt. Register annotated functions through ProcessProvider.addTools(org.machanism.machai.process.tools.FunctionTools, String[]) rather than calling the protected registration hook directly.

Supporting utilities

ToolLogger records tool, prompt, and resource invocation details while abbreviating payloads at INFO level and retaining complete payloads at DEBUG level. TypeConverter converts reflected tool parameters from string or JSON representations and maps Java parameter types to simplified schema type names. These utilities support the provider infrastructure and are not provider-selection mechanisms.

Typical usage

The following example registers annotated host functions and dispatches a YAML request. The YAML tool value must match a registered function name; the Configurator setup is application-specific.

 ProcessProvider provider = new ToolsProvider();
 provider.init("yaml", configurator);
 provider.addTools(functionTools, null);
 provider.prompt("tool: summarize\nparams:\n  path: README.md");
 String result = provider.perform();
 provider.clear();
 

Use the no-op implementation when processing must be deliberately disabled:

 ProcessProvider provider = new NoneProvider();
 provider.init("log", configurator);
 provider.prompt("This input is accepted and discarded.");
 String result = provider.perform(); // always null
 

Since:

1.2.0

See Also:

• ProcessProvider
• EmbeddingProvider
• AbstractAIProvider
• ProcessProviderAdapter
• NoneProvider
• ToolsProvider
• ToolLogger
• TypeConverter

Class	Description
AbstractAIProvider	Base implementation of the ProcessProvider contract shared by concrete provider integrations.
EmbeddingProvider	EmbeddingProvider defines the contract for AI embedding providers.
NoneProvider	No-op implementation of ProcessProvider that performs no AI processing.
ProcessProvider	Contract for a generative-AI provider integration.
ProcessProviderAdapter	Delegating ProcessProvider implementation.
ToolLogger	Internal logging utility for tool inputs, results, and execution errors.
ToolLogger.Type	Defines the types of operations whose activity can be logged.
ToolsProvider	AI provider implementation for managing and invoking host-defined function tools.
TypeConverter	Utility class for converting between Java types and their string representations, as well as mapping Java types to simplified type names (e.g., "string", "integer", "array").