Docs & Demo: Integrate Ozwell AI API for contextual assistant and builder actions

[lattln]

Description

The eSheet platform currently lacks an integrated assistant to help users navigate documentation or interact with the demo builder.

This ticket introduces integration with the Ozwell AI API across two contexts:

1. Documentation Site

   • Provide a contextual AI assistant that answers questions strictly based on documentation content
   • Guide users by referencing relevant sections and pages

2. Demo / Builder Environment

   • Extend the assistant to support tool-based interactions
   • Enable users to create, modify, or interact with the form builder via exposed functions (tools)

This establishes a unified AI layer that adapts behavior based on application context:

• Docs → Read-only, knowledge-based assistant
• Demo → Actionable assistant with tool execution

---

Problem / Motivation

• Documentation is static and requires manual navigation
• No guided onboarding or contextual help for users
• Demo builder lacks discoverability for features and workflows
• Users must learn APIs and builder behavior without assistance

As eSheet grows:

• Support overhead increases
• UX becomes fragmented between docs and demo
• Advanced capabilities (builder, fields, logic) remain underutilized

Introducing an AI assistant:

• Reduces friction in learning and usage
• Improves discoverability of features
• Enables natural-language interaction with the builder

---

Scope

Documentation Site Behavior

• AI assistant operates in read-only mode
• Answers are strictly grounded in documentation
• Provides references to relevant sections/pages
• No tool execution or state mutation

Demo / Builder Behavior

• AI assistant operates in tool-enabled mode

• Can invoke predefined functions (tools) to:

  • Create fields
  • Modify field properties
  • Interact with builder state

• Responses may include both explanation and action

---

Acceptance Criteria

Core Integration

• Ozwell AI API is integrated into the docs and demo applications
• Shared AI client layer supports both read-only and tool-enabled modes
• Context detection (docs vs demo) determines assistant capabilities

Documentation Assistant

• Assistant answers are derived from documentation content only
• Responses include references or links to relevant sections
• No builder or mutation actions are available
• UI is accessible across all documentation pages
• Graceful fallback if API is unavailable

Demo / Builder Assistant

• Assistant can call exposed builder tools/functions
• Tool execution results correctly update builder state
• Clear separation between explanation vs action responses
• User can confirm or trigger actions (if required by UX)
• Errors in tool execution are handled gracefully

Tooling Layer

• Define a clear tool interface compatible with Ozwell AI API

• Initial tool set includes:

  • Create field
  • Update field
  • Remove field
  • Select/focus field

• Tools are scoped to demo environment only

---

Notes / Constraints

• Repositories:

  • eSheet: https://github.com/mieweb/esheet
  • Ozwell API: https://github.com/mieweb/ozwellai-api
  • API Docs: https://mieweb.github.io/ozwellai-api/

• Assistant behavior must be context-aware

  • Docs = strictly informational
  • Demo = interactive + functional

• Avoid hallucinated tool execution:

  • All actions must map to explicitly defined tools

• Keep AI integration loosely coupled:

  • Abstract API client layer
  • Avoid hard dependency inside core builder logic

• Consider performance:

  • Lazy-load assistant
  • Avoid blocking initial page render

---

Future Considerations (Out of Scope)

• Persisting AI-driven changes as versioned builder actions
• Multi-step workflows (e.g., “create full form from prompt”)
• User personalization or memory
• Voice or multimodal inputs

---

If you want next step, I can break this into epics + sub-tickets like:

• AI Client Layer
• Docs Ingestion Pipeline
• Builder Tool Registry
• UI Chat Panel (shared component)

That would align well with how you’ve been structuring work across packages.