An Org Babel backend for gptel.

I've been using GPTel a lot lately, for many different tasks, and wanted a way to embed AI conversations right into my Org documents. ob-gptel does this -- you write a prompt in a #+begin_src gptel block, press C-c C-c, and the response appears in the results. It's fully asynchronous, so Emacs doesn't block while waiting.

Thanks to some late night pairing with Karthik (author of GPTel), ob-gptel handles multi-turn conversations, preset configurations, context injection, and dry-run mode for inspecting API payloads without sending them.

• Emacs 25.1+
• Org mode 9.0+
• gptel 0.9.8.5+

(straight-use-package
 '(ob-gptel :type git :host github :repo "jwiegley/ob-gptel"))

Clone this repository, add it to your load path, and require it:

(add-to-list 'load-path "/path/to/ob-gptel")
(require 'ob-gptel)

Register gptel as a Babel language:

(org-babel-do-load-languages
 'org-babel-load-languages
 '((gptel . t)))

For completion of header argument names and values in gptel blocks:

(add-hook 'completion-at-point-functions 'ob-gptel-capf nil t)

Or with use-package:

(use-package ob-gptel
  :config
  (add-to-list 'org-babel-load-languages '(gptel . t))
  (defun ob-gptel-setup-completions ()
    (add-hook 'completion-at-point-functions
              'ob-gptel-capf nil t))
  :hook (org-mode . ob-gptel-setup-completions))

#+begin_src gptel
What is the capital of France?
#+end_src

#+RESULTS:
The capital of France is Paris.

#+begin_src gptel :model gpt-4 :temperature 0.7 :max-tokens 150
Write a haiku about Emacs.
#+end_src

#+begin_src gptel :system "You are a helpful coding assistant."
How do I define a major mode in Emacs?
#+end_src

There are two ways to build conversations. The :prompt header argument references a named block, sending its body and result as a user/assistant turn:

#+name: setup
#+begin_src gptel :system "You are a math tutor."
What is the Pythagorean theorem?
#+end_src

#+RESULTS: setup
a^2 + b^2 = c^2

#+begin_src gptel :prompt setup
Can you give me an example?
#+end_src

The :session argument collects all preceding blocks that share the same session name:

#+begin_src gptel :session my-chat
Tell me about Emacs.
#+end_src

#+begin_src gptel :session my-chat
What about its history?
#+end_src

If you've configured gptel presets, you can use them:

#+begin_src gptel :preset claude
Explain monads simply.
#+end_src

Inspect the API payload without actually sending a request:

#+begin_src gptel :dry-run yes
What would this request look like?
#+end_src

In a literate DevOps context, you can have gptel generate commands:

#+begin_src gptel :preset gpt :wrap src sh
GNU find command to search /tmp for files with 2+ hard-links.
Show only the final command.
#+end_src

#+RESULTS:
#+begin_src sh
find /tmp -type f -links +1
#+end_src

This project uses Nix for reproducible builds and development.

# Enter development shell
nix develop

# Run all checks
nix flake check

# Build the package
nix build

# Format code
nix run .#format

Lefthook handles pre-commit hooks. Once inside nix develop:

lefthook install

BSD 3-Clause. See LICENSE.md.