Masamune AI

[GitHub] | [YouTube] | [Packages] | [X] | [LinkedIn] | [mathru.net]

Masamune AI #

Overview #

• masamune_ai is a generative AI integration library for the Masamune framework.
• Configure AI behavior through the adapter (AIMasamuneAdapter), including Model Context Protocol (MCP) settings.
• Use AIThread to manage multi-turn conversations and AISingle for single-turn prompts.
• Manage tool integrations via the MCP client (McpClient) and AITool.

Setup #

1. Add the package to your project.

Note: This is the base package. You'll also need a concrete implementation:

• masamune_ai_firebase for Firebase Vertex AI / Gemini
• masamune_ai_openai for OpenAI ChatGPT

flutter pub add masamune_ai
flutter pub add masamune_ai_firebase  # or masamune_ai_openai

2. Register an AI adapter in MasamuneApp.

void main() {
  runApp(
    MasamuneApp(
      appRef: appRef,
      adapters: const [
        // Use FirebaseAIMasamuneAdapter or OpenaiAIMasamuneAdapter
        // See implementation-specific packages for details
      ],
    ),
  );
}

AIMasamuneAdapter #

• Implements common AI initialization and configuration logic.
• Provide the following when extending:
  • defaultConfig: an AIConfig describing the model, system prompt, and response schema.
  • initialize and generateContent: connect to the actual AI service.
  • mcpServerConfig, mcpClientConfig, mcpFunctions: settings for MCP integration.
  • contentFilter and onGenerateFunctionCallingConfig: preprocess content or control function-calling retries.

Runtime Adapter Example #

Use RuntimeAIMasamuneAdapter for tests or mock implementations.

class MockAdapter extends RuntimeAIMasamuneAdapter {
  const MockAdapter()
      : super(
          onGenerateContent: (contents, config) async {
            final response = AIContent.model(text: "Mock response!");
            response.complete();
            return response;
          },
        );
}

Concrete Implementations #

Firebase AI Adapter (masamune_ai_firebase)

• Provides FirebaseAIMasamuneAdapter for Firebase Vertex AI / Gemini models
• Requires Firebase initialization and supports FirebaseAIModel (gemini-2.0-flash, etc.)
• Includes Vertex AI function-calling support for MCP tools
• See masamune_ai_firebase package for detailed setup

OpenAI Adapter (masamune_ai_openai)

• Provides OpenaiAIMasamuneAdapter for OpenAI ChatGPT models
• Requires an OpenAI API key and supports OpenaiAIModel (gpt-4o, gpt-5-mini, etc.)
• Streams responses from Chat Completions API
• Includes OpenaiChatGPTFunctionsAction for backend Functions integration
• See masamune_ai_openai package for detailed setup

AIConfig and AITool #

• AIConfig: holds the model name, system prompt (AIContent.system), and response schema (AISchema).
• AITool: defines a tool that can be invoked through MCP or function calls.

final weatherTool = AITool(
  name: "weather",
  description: "Get the current weather",
  parameters: {
    "city": AISchema.string(description: "City name"),
  },
);

Conversation Management with AIThread #

• Maintains a list of AIContent exchanges and supports multi-turn conversations.
• Call initialize to set up the model, then generateContent to send user input and receive responses.

final thread = ref.app.controller(
  AIThread.query(
    threadId: "chat-1",
    initialContents: [
      AIContent.text("Hello!"),
    ],
  ),
);

final updatedContents = await thread.generateContent(
  [AIContent.text("Tell me the latest news")],
  config: AIConfig(model: "gpt-4o-mini"),
  tools: {weatherTool},
);

Single Interaction with AISingle #

• Use when only one response is needed.

final single = ref.app.controller(
  AISingle.query(
    config: AIConfig(model: "gpt-4o-mini"),
  ),
);

final result = await single.generateContent([
  AIContent.text("Summarize this"),
]);

MCP Client Integration #

• McpClient loads tools from an MCP server and processes AI function calls.

final mcpClient = ref.app.controller(McpClient.query());
await mcpClient.load();
final toolResult = await mcpClient.call("weather", {"city": "Tokyo"});

• When mcpClientConfig and mcpFunctions are configured in the adapter, AIThread and AISingle automatically invoke tools through MCP during generateContent.

Working with AIContent #

• Represents messages exchanged with the model.
• Factory constructors support multiple data types: AIContent.text, AIContent.png, AIContent.system, and more.
• Use AIContentFunctionCallPart and AIContentFunctionResponsePart to model structured function calls.
• Streamed responses can be handled via add, complete, and error.

Typical Workflow #

1. Register a custom AIMasamuneAdapter in MasamuneApp.
2. Obtain AIThread or AISingle via ref.app.controller.
3. Optionally load MCP tools.
4. Call generateContent with user AIContent.
5. Render the AI response from the controller’s value.
6. Handle function calls via MCP or custom logic.

Common Customizations #

• System Prompt: Provide AIConfig.systemPromptContent with AIContent.system.
• Response Schema: Define structured JSON outputs using AISchema.
• Usage Tracking: Inspect onGeneratedContentUsage for prompt and candidate token counts.
• Content Filtering: Apply contentFilter or per-call filters to sanitize requests.
• Function Calling Control: Customize retries or forced execution with onGenerateFunctionCallingConfig.

Development Tips #

• Follow Masamune controller patterns (appRef, ref.app.controller) for lifecycle-aware access.
• Monitor the loading future on AIContent for streaming updates.
• Even without MCP, the adapter’s onFunctionCall must return an empty list to satisfy the interface.

GitHub Sponsors #

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet