guide_ai 0.1.0-alpha.2

AI-guided app assistant and walkthrough SDK for Flutter apps.

GuideAI Flutter SDK

guide_ai is the MVP alpha Flutter SDK for GuideAI-powered in-app assistance and guided walkthroughs.

MVP alpha status

• Alpha package for manual GuideAI registration
• Manual page registration is required
• Manual element registration is required
• Manual workflow registration is required
• No automatic widget discovery
• No automatic page discovery
• No automatic navigation

What it does

• Resolves end-user questions into guided workflows
• Renders an assistant chat sheet inside your Flutter app
• Highlights registered widgets with a walkthrough overlay
• Continues workflows across screens when the current page changes
• Surfaces validation, health, and debug diagnostics for manual SDK setup

What it does not do yet

• Automatic widget discovery
• Automatic page discovery
• Automatic route-to-page mapping without your registration
• Automatic workflow authoring inside the SDK

Installation

dependencies:
  guide_ai: ^0.1.0-alpha.2

import 'package:guide_ai/guide_ai.dart';

Backend contract

• Official backend endpoint: POST /v1/workflows/resolve-page-context
• The Flutter SDK sends a page-grouped contract: appContext.pages[]
• Each registered page includes its registered elements

Quick start

import 'package:flutter/material.dart';
import 'package:guide_ai/guide_ai.dart';

final bookTicketButtonKey = GlobalKey();
final sourceStationKey = GlobalKey();

void setupGuideAI() {
  GuideAI.init(
    config: GuideAIConfig(
      appId: 'your-app-id',
      apiKey: 'YOUR_GUIDEAI_API_KEY',
      baseUrl: 'https://your-guideai-backend.example.com',
      appName: 'Your Flutter App',
      debugMode: true,
      theme: const GuideAITheme(),
    ),
  );

  GuideAI.registerPage(
    pageId: 'home',
    pageName: 'Home',
    route: '/',
    description: 'Landing page',
  );

  GuideAI.registerElement(
    pageId: 'home',
    elementId: 'book_ticket_button',
    key: bookTicketButtonKey,
    label: 'Book Ticket',
    type: 'button',
    action: 'navigate',
    targetPageId: 'book_ticket',
  );

  GuideAI.registerPage(
    pageId: 'book_ticket',
    pageName: 'Book Ticket',
    route: '/book-ticket',
  );

  GuideAI.registerElement(
    pageId: 'book_ticket',
    elementId: 'source_station_input',
    key: sourceStationKey,
    label: 'Source Station',
    type: 'text_field',
    action: 'input',
  );

  GuideAI.registerWorkflow(
    const GuideAIRegisteredWorkflow(
      workflowName: 'book_ticket',
      title: 'Book a Train Ticket',
      keywords: <String>['book', 'ticket'],
      steps: <GuideAIWorkflowStep>[
        GuideAIWorkflowStep(
          stepId: 'step_001',
          order: 1,
          pageId: 'home',
          elementId: 'book_ticket_button',
          instruction: 'Tap Book Ticket.',
          actionType: 'navigate',
        ),
        GuideAIWorkflowStep(
          stepId: 'step_002',
          order: 2,
          pageId: 'book_ticket',
          elementId: 'source_station_input',
          instruction: 'Enter the source station.',
          actionType: 'input',
        ),
      ],
    ),
  );

  GuideAI.setCurrentPage('home');
}

Initialization

Call GuideAI.init(...) once during app startup. The package validates:

• appId
• apiKey
• baseUrl
• request timeout configuration

Use a real backend URL in production. Placeholder example:

GuideAI.init(
  config: GuideAIConfig(
    appId: 'your-app-id',
    apiKey: 'YOUR_GUIDEAI_API_KEY',
    baseUrl: 'https://your-guideai-backend.example.com',
  ),
);

Backend URL and API key configuration

• baseUrl should point to your GuideAI backend host
• apiKey should be supplied by your backend or developer configuration
• Do not ship demo keys or localhost defaults in production builds

Manual page registration

GuideAI.registerPage(
  pageId: 'checkout',
  pageName: 'Checkout',
  route: '/checkout',
  description: 'Checkout screen',
);

Manual element registration

Register widgets with stable GlobalKey instances.

final payNowKey = GlobalKey();

GuideAI.registerElement(
  pageId: 'checkout',
  elementId: 'pay_now_button',
  key: payNowKey,
  label: 'Pay Now',
  type: 'button',
  action: 'submit',
);

Manual workflow registration

GuideAI.registerWorkflow(
  const GuideAIRegisteredWorkflow(
    workflowName: 'complete_checkout',
    title: 'Complete Checkout',
    keywords: <String>['checkout', 'pay'],
    steps: <GuideAIWorkflowStep>[
      GuideAIWorkflowStep(
        stepId: 'step_pay_now',
        order: 1,
        pageId: 'checkout',
        elementId: 'pay_now_button',
        instruction: 'Tap Pay Now to submit the order.',
      ),
    ],
  ),
);

Assistant UI setup

Wrap your app once with GuideAIScope so the package can render the assistant chat sheet, walkthrough overlay, and optional debug panel.

MaterialApp(
  navigatorObservers: <NavigatorObserver>[
    GuideAINavigatorObserver(),
  ],
  builder: (context, child) {
    return GuideAIScope(
      child: child ?? const SizedBox.shrink(),
    );
  },
);

GuideAIScope automatically manages the built-in GuideAIFab.

Navigator observer setup

If your app uses named routes, add GuideAINavigatorObserver() so the SDK can react to route changes and continue multi-screen workflows more reliably.

Theme customization

GuideAITheme is implemented and can be passed into GuideAIConfig.

GuideAI.init(
  config: GuideAIConfig(
    appId: 'your-app-id',
    apiKey: 'YOUR_GUIDEAI_API_KEY',
    baseUrl: 'https://your-guideai-backend.example.com',
    theme: const GuideAITheme(
      primaryColor: Color(0xFF0A6EBD),
    ),
  ),
);

Asking questions and starting walkthroughs

End users can open the built-in assistant with:

GuideAI.openAssistant();

If you need to resolve a question programmatically, use the public controller:

final response = await GuideAI.controller.askQuestion(
  'How do I complete checkout?',
);

if (response?.workflow != null) {
  GuideAI.startWorkflow(response!.workflow);
}

Starting and controlling walkthroughs

Implemented controls include:

• GuideAI.startWorkflow([workflow])
• GuideAI.markStepCompleted(elementId)
• GuideAI.clearActiveWorkflow()
• GuideAI.pauseWorkflow()
• GuideAI.resumeWorkflow()
• GuideAI.resetSession()

Example:

GuideAI.startWorkflow();
GuideAI.markStepCompleted('pay_now_button');
GuideAI.pauseWorkflow();
GuideAI.resumeWorkflow();

Health check and diagnostics

These APIs are implemented:

• GuideAI.healthCheck()
• GuideAI.validateSetup()
• GuideAI.getDebugState()
• GuideAI.exportDebugSnapshot()

final validation = GuideAI.validateSetup();
final health = await GuideAI.healthCheck();
final debugState = GuideAI.getDebugState();

Missing element recovery

If a registered widget is not mounted or not on the current screen, the SDK:

• keeps the workflow active
• shows recovery UI instead of crashing
• waits for the correct page
• resumes highlighting when the target widget becomes available

Cross-screen continuation

The SDK supports workflows that continue across multiple registered screens. Keep GuideAI.setCurrentPage(pageId) updated whenever your app changes screens.

GuideAI.setCurrentPage('book_ticket');

Known limitations

• MVP alpha package
• Manual registration model only
• No automatic widget discovery
• No automatic page discovery
• No automatic navigation
• Widgets must be mounted before they can be highlighted

License

MIT