Skip to content

Add Type Ahead experiment #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Jameswlepage wants to merge 5 commits into
base: develop
Choose a base branch
from
Draft

Add Type Ahead experiment #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
31446fb
Add Type Ahead experiment
Jameswlepage Dec 18, 2025
4f7fa7a
Fix PHPCS issues in type-ahead files
Jameswlepage Dec 19, 2025
e30564d
Fix type-ahead: use get_preferred_models() helper function
Jameswlepage Dec 19, 2025
320d158
Improve type-ahead: use faster models and lower overlay z-index
Jameswlepage Dec 19, 2025
850d097
Merge branch 'develop' into feature/type-ahead
jeffpaul Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/experiments/type-ahead.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Type Ahead

## Summary
Adds inline "ghost text" completions to the block editor. When the experiment and global toggle are enabled, typing inside supported blocks (paragraphs by default, optional headings) displays translucent suggestions that can be accepted via keyboard shortcuts.

## Key Hooks & Entry Points
- `WordPress\AI\Experiments\Type_Ahead\Type_Ahead::register()` hooks `wp_abilities_api_init` to register the AI ability and `enqueue_block_editor_assets` to load assets only when the block editor runs.
- `Type_Ahead::register_settings()` stores experiment-specific options under the Experiments settings screen (`ai_experiment_type_ahead_*`).
- `src/experiments/type-ahead/index.tsx` registers an `editor.BlockEdit` filter (HOC) that adds the overlay for each supported block and wires keyboard handlers.
- Ability implementation lives at `includes/Abilities/Type_Ahead/Type_Ahead.php` and is registered as `ai/type-ahead`.

## Assets & Data Flow
1. PHP enqueues the `experiments/type-ahead` script and `experiments/style-type-ahead` stylesheet, then localizes `aiTypeAheadData` with flags like `completionMode`, `triggerDelay`, and `abilityName`.
2. The React entry point polls for the localized data, then wraps block edits to render the overlay component and keyboard hints, and calls `executeAbility( 'ai/type-ahead', ... )` when it is time to request a suggestion.
3. The ability sanitizes input (post ID, caret position, snippets of block content) and composes a structured payload via `prepare_prompt_context()`.
4. `AI_Client::prompt_with_wp_error()` is invoked with the system instruction in `includes/Abilities/Type_Ahead/system-instruction.php`, returning JSON `{ suggestion, confidence }` that the ability validates before passing back to JS.
5. The UI caches the last suggestion per block/caret, displays it via a portal near the caret, and dispatches synthetic `input` events when the user accepts a suggestion so Gutenberg updates its state.

## Testing
1. Enable Experiments globally and toggle **Type-ahead Text** under `Settings > AI Experiments`. (Optional: adjust mode/delay/confidence/headings.)
2. Open the block editor, insert a Paragraph block, and start typing sentences until the caret is at the end of a sentence. After the configured delay a faint suggestion should appear.
3. Press `Tab` to accept the full suggestion, `Cmd/Ctrl + Right Arrow` for a word, or `Cmd/Ctrl + Shift + Right Arrow` for a sentence. The accepted text should become real content and the remainder should stay ghosted if available.
4. Press `Esc` to dismiss a suggestion. Use `Cmd/Ctrl + Space` to force a manual fetch even when the caret context would not auto-trigger.
5. Toggle the "Enable in headings" checkbox in settings, then verify `core/heading` blocks now receive suggestions.

## Notes
- Suggestions are cached briefly (45 seconds) per block/caret combination to reduce provider calls.
- Permissions require `edit_post` when a post ID is provided, otherwise `edit_posts`.
- The ability trims contexts to 5000 characters and normalizes HTML content before sending it to the model.
- Settings are stored via the standard options API; sanitizers enforce safe ranges (delay 200-2000 ms, confidence 0-100, etc.).
- The client aborts long-running REST calls after roughly 15 seconds to avoid default 20s browser/`apiFetch` timeouts while still giving the server time; writers can press Cmd/Ctrl + Space to manually try again.
Loading
Loading