Skip to content

Contributing guidelines

Jump to bottom
oobabooga edited this page May 17, 2026 · 23 revisions

Contributing guidelines

  1. Please submit your changes to the main branch of the repository.
  2. Thoroughly self-test your code. Can you think of a scenario where it might not work as expected? Does it interfere with other parts of the program?
  3. Keep it simple, structured, and organized. Do not add more lines than you have to.

AI usage policy

AI-assisted contributions are welcome. Use whatever helps you ship better code: Claude Code, Codex, Aider, Cline, etc. In particular, running an AI review of your own PR before submitting it is strongly encouraged and tends to catch the kinds of small issues that would otherwise require a round trip.

Scope

The UI is built with Gradio 4. See the docs here: https://www.gradio.app/4.44.1/docs/gradio/interface

Project structure
  • shared.settings contains default values for Gradio components. It can be customized through a settings.yaml file.
  • shared.args contains the command-line arguments. They represent variables that need to be changed often.
  • shared.gradio contains the UI elements, like sliders and dropdowns. When defining Gradio event handlers, the gradio function in modules.utils can be used to write
gradio('history', 'character_menu', 'mode')

instead of

[shared.gradio[k] for k in ['history', 'character_menu', 'mode']]
  • The UI values are not passed directly to the generation functions. Instead, they are first fed into the shared.gradio['interface_state'] state variable. This variable receives the name state when used as input to backend functions. The code for updating shared.gradio['interface_state'] with the current UI values is the following (see server.py for several examples):
ui.gather_interface_values, gradio(shared.input_elements), gradio('interface_state')
  • The chat history is represented as a dictionary with the following structure:
{
    'internal': [['hi', 'hey'], ['how are you?', "i'm fine, thanks!"]],
    'visible': [['hi', 'hey'], ['how are you?', "i'm fine, thanks!"]]
}

Each row is in the format [input, reply]. history['visible'] contains the messages as they will appear in the UI, and history['internal'] contains the messages as they appear in the prompt. When no extension is used, the two will be identical, but many extensions add images, audio widgets, or translations to history['visible'].

Extensions

As a rule of thumb, new extensions should be submitted to https://github.com/oobabooga/textgen-extensions. You are highly encouraged to submit your extensions to that list!

New built-in extensions can be accepted in cases where they would be useful to a large percentage of the user base, preferably while adding few or no additional dependencies.

Clone this wiki locally