Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (74 loc) · 3.34 KB

AGENTS.md

File metadata and controls

91 lines (74 loc) · 3.34 KB

Project Overview: Visualizations for OpenWebUI

Core Concept

  • Plugin for OpenWebUI that enables LLMs to generate visual content without API calls
  • Uses Markdown image URLs pointing to dynamic endpoints - no function calling required
  • LLMs generate Markdown like ![chart](.../visualization/chart.png?spec=...) and server renders visualizations

Architecture

  • Build system: Concatenates src/ files into single build/visualization.py for OpenWebUI
  • Filter-based: Injects visualization instructions into system prompt via OpenWebUI filter
  • Multiple visualization types: Charts, Generative Images, Fancy Text, Large Emoji, QR Codes, Color Swatches, etc

Key Technical Details

  • Authentication: Uses pass.txt with auto-generated token for URL security
  • Data handling: Charts fetch external data URLs and embed them at render time
  • Frontend enhancement: Injects JavaScript for loading states and aspect ratio handling
  • Dependency resolution: Build system analyzes imports and orders files topologically

Development Workflow

  • Work in src/ directory only - never edit build/visualization.py directly
  • Use ./build.sh to concatenate and format the plugin

Where the code lives

The src directory is where the code is at. You'll mainly work with these file.

How to build and test

Use ./build.sh to build the project.

NEVER read whole build/visualization.py

The file build/visualization.py is way too long to be read as a whole. It is the concatenation file of all the files in src. If you read all of it you will nuke your context window. You can use the head command or search within it if you must. But the real work is supposed to take place in src anyways.

Comment Preferences

Keep

  • Major section dividers (with === characters)
  • Process step comments that mark logical sections (e.g., "# --- Measure Text ---")
  • Explanatory comments that provide context not obvious from code
  • Inline comments that explain "why" something is done
  • Inline explanations after code (e.g., "# token_urlsafe(9) gives ~12 chars")

Remove

  • All function docstrings
  • Obvious section comments (e.g., "# Constants")
  • Obvious inline comments that just state what code is doing
  • Redundant comments that restate what the code does
  • Comments like "# Generate new pass" where the code is self-explanatory

Using apply_diff Tool

Correct Format

<apply_diff>
<args>
  <file>
    <path>relative/path/to/file.ext</path>
    <diff>
      <content>
<<<<<<< SEARCH
:start_line:14
-------
[exact content to find including whitespace]
=======
[new content to replace with]
>>>>>>> REPLACE
</content>
    </diff>
  </file>
</args>
</apply_diff>

What to AVOID

  • NEVER use CDATA markers: Don't wrap content in <![CDATA[ ... ]]>
  • NEVER mix git-diff format: Use the exact XML structure shown above
  • NEVER add extra markers: Only use <<<<<<< SEARCH, =======, and >>>>>>> REPLACE
  • ALWAYS match exact content: The SEARCH content must exactly match the file including whitespace
  • ALWAYS include correct line numbers: Use :start_line: parameter

Best Practices

  • Use apply_diff for surgical edits to existing code
  • Use write_to_file for creating new files or complete rewrites
  • Include multiple SEARCH/REPLACE blocks in one apply_diff when possible
  • Always verify content with read_file before applying diffs