Add docs

* improve a few error messages
* test empty prompts

Author: slimslenderslacks

README.md

@@ -34,46 +34,8 @@ OpenAI API compatiable LLM's already support function calling. This is our workb
 - work across a wider range of environments
 - operate in a sandboxed environment
 
-
 # Get Started
 
-## Basics: Render a Prompt
-
-To generate prompts for a project, clone a repo into `$PWD` and run the 
-following command.
-
-```sh
-docker run --rm \
-           --pull=always \
-           -v /var/run/docker.sock:/var/run/docker.sock \
-           --mount type=volume,source=docker-prompts,target=/prompts \
-           vonwig/prompts:latest --host-dir $PWD \
-                                 --user jimclark106 \
-                                 --platform darwin \
-                                 --prompts-dir "github:docker/labs-make-runbook?ref=main&path=prompts/lazy_docker"
-```
-
-The four arguments are 
-* `project root dir on host`, 
-* `docker login username`, 
-* `platform`, 
-* `github ref` for prompt files.
-
-If you need to test prompts before you push, you can bind a local prompt directory instead of using
-a GitHub ref.  For example, to test some local prompts in a directory named `my_prompts`, run:
-
-```sh
-docker run --rm \
-           --pull=always \
-           -v /var/run/docker.sock:/var/run/docker.sock \
-           --mount type=bind,source=$PWD,target=/app/my_prompts \
-           --workdir /app \
-           vonwig/prompts:latest --host-dir $PWD \
-                                 --user jimclark106 \
-                                 --platform darwin \
-                                 --prompts-dir my_prompts
-```
-
 ## Running a Conversation Loop
 
 Set OpenAI key
@@ -82,51 +44,23 @@ echo $OPENAI_API_KEY > $HOME/.openai-api-key
 ```
 Run
 ```sh
-docker run --rm \
-           -it \
-           -v /var/run/docker.sock:/var/run/docker.sock \
-           --mount type=volume,source=docker-prompts,target=/prompts \
-           --mount type=bind,source=$HOME/.openai-api-key,target=/root/.openai-api-key \
-           vonwig/prompts:latest \
-                                 run \
-                                 --host-dir $PWD \
-                                 --user $USER \
-                                 --platform "$(uname -o)" \
-                                 --prompts "github:docker/labs-githooks?ref=main&path=prompts/git_hooks"
-```
-
-### Running a Conversation Loop with Local Prompts
-
-If you want to run a conversation loop with local prompts then you need to think about two different directories, the one that the root of your project ($PWD above), 
-and the one that contains your prompts (let's call that $PROMPTS_DIR).  Here's a command line for running the prompts when our $PWD is the project root and we've set the environment variable
-$PROMPTS_DIR to point at the directory containing our prompts.
-
-Set OpenAI key
-```sh
-echo $OPENAI_API_KEY > $HOME/.openai-api-key
-```
-Run
-```sh
-docker run --rm \
-           -it \
-           -v /var/run/docker.sock:/var/run/docker.sock \
-           --mount type=bind,source=$PROMPTS_DIR,target=/app/my_prompts \
-           --workdir /app \
-           --mount type=volume,source=docker-prompts,target=/prompts \
-           --mount type=bind,source=$HOME/.openai-api-key,target=/root/.openai-api-key \
-           vonwig/prompts:latest \
-                                 run \
-                                 --host-dir $PWD \
-                                 --user $USER \
-                                 --platform "$(uname -o)" \
-                                 --prompts-dir my_prompts
-```
-
-## GitHub refs
-
-Prompts can be fetched from a GitHub repository when using the `--prompts` arg.  The mandatory parts of the ref are `github:{owner}/{repo}` 
-but optional `path` and `ref` can be added to pull prompts from branches, and to specify a subdirectory
-where the prompt files are located in the repo.
+docker run 
+  --rm \
+  --pull=always \
+  -it \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  --mount type=volume,source=docker-prompts,target=/prompts \
+  --mount type=bind,source=$HOME/.openai-api-key,target=/root/.openai-api-key \
+  vonwig/prompts:latest \
+    run \
+    --host-dir $PWD \
+    --user $USER \
+    --platform "$(uname -o)" \
+    --prompts "github:docker/labs-githooks?ref=main&path=prompts/git_hooks"
+```
+
+See [docs](https://vonwig.github.io/prompts.docs/#/page/running%20the%20prompt%20engine) for more details on how to run the conversation loop, 
+and especially how to use it to run local prompts that are not yet in GitHub.
 
 ## Function volumes
 

prompts/hub/default.md

@@ -0,0 +1,4 @@
+
+# prompt user
+
+What is the meaning of life?

prompts/hub/figlet.md

@@ -1,13 +1,10 @@
 ---
-functions:
+tools:
   - name: figlet
 ---
 
 # Prompt user
 
-Run figlet on the message `Docker`.
-
-# Result
-
-run a man page
+Read the figlet man page.
+Next, run figlet on the message `Docker` using the font future.
 

prompts/hub/fzf.md

@@ -1,5 +1,5 @@
 ---
-functions:
+tools:
   - name: fzf
 ---
 
@@ -13,18 +13,11 @@ searching your shell history.
 * `Alt-c` to switch directories
 * `Ctrl-r` to search command history
 
-# Example user
+# Prompt user
 
 Read the man page for `fzf` and summarize what it does.
 
 # Prompt user
 
 Use fzf to search the /project folder for any files that contain the word 'Prompt'
 
-# Result
-
-run a man page
-
-what is fzf for?
-
-

prompts/hub/toilet.md

@@ -1,13 +1,9 @@
 ---
-functions:
+tools:
   - name: toilet
 ---
 
 # Prompt user
 
 First run the man page for toilet.
 After that, run the toilet command with the font `helvetica` and write the message "Hello from Docker"
-
-# Result
-
-run a man page

prompts/hub/typos.md

@@ -1,16 +1,12 @@
 ```
-funcions:
+tools:
   - name: typos
 ```
 
 # Prompt user
 
-Use the the `typos` command to find typos in the following sentence.
+Use the `typos` command to find typos in the following sentence.
 
 ```
 Hella my nome is Jim.
 ```
-
-# Result
-
-The AI should know how to use this command.

prompts/qrencode/README.md

@@ -1,14 +1,11 @@
 ---
-tool_choice: auto
-functions:
+tools:
   - name: qrencode
 ---
 
 # Prompt user
 
-Generate a QR code for the content `https://github.com/docker/labs-ai-tools-for-dev`. Save the generated image to `qrcode.png`.
+Generate a QR code for the content 
+'https://raw.githubusercontent.com/docker/labs-ai-tools-for-devs/main/prompts/qrencode/README.md'.
+Save the generated image to `qrcode.png`.
 If the command fails, read the man page and try again.
-
-# Result
-
-This function generates a QR code for a URL. The QR code is saved as a PNG file.

runbook.md

@@ -185,19 +185,21 @@ bb -m prompts run \
 #### Using Containerized runner
 
 ```sh
-docker run --rm \
-          -it \
-           -v /var/run/docker.sock:/var/run/docker.sock \
-           --mount type=bind,source=$PWD,target=/app/local \
-           --workdir /app \
-           --mount type=volume,source=docker-prompts,target=/prompts \
-           --mount type=bind,source=$HOME/.openai-api-key,target=/root/.openai-api-key \
-           vonwig/prompts:local \
-                                 run \
-                                 --host-dir /Users/slim/docker/labs-make-runbook \
-                                 --user jimclark106 \
-                                 --platform "$(uname -o)" \
-                                 --prompts-dir local/prompts/dockerfiles
+docker run 
+  --rm \
+  --pull=always \
+  -it \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  --mount type=bind,source=$PWD,target=/app/local \
+  --workdir /app \
+  --mount type=volume,source=docker-prompts,target=/prompts \
+  --mount type=bind,source=$HOME/.openai-api-key,target=/root/.openai-api-key \
+  vonwig/prompts:local \
+    run \
+    --host-dir /Users/slim/docker/labs-make-runbook \
+    --user jimclark106 \
+    --platform "$(uname -o)" \
+    --prompts-dir local/prompts/dockerfiles
 ```
 
 ### Clean up local images

src/docker.clj

@@ -2,6 +2,7 @@
   (:require
    [babashka.curl :as curl]
    [cheshire.core :as json]
+   [clojure.core.async :as async]
    [clojure.pprint :refer [pprint]]
    [clojure.spec.alpha :as spec]
    [clojure.string :as string]
@@ -195,24 +196,38 @@
 (spec/def ::container-definition (spec/keys :opt-un [::host-dir ::entrypoint ::command ::user ::pat]
                                             :req-un [::image]))
 
-(defn run-function [m]
+(defn run-function [{:keys [timeout] :or {timeout 600000} :as m}]
   (pull (merge m
                {:serveraddress "https://index.docker.io/v1/"}
                (let [jwt (creds/credential-helper->jwt)]
                  (when (and (:user m)
                             (or (:pat m) jwt))
                    {:creds {:username (:user m)
                             :password (or (:pat m) jwt)}}))))
-  (let [x (create m)]
+  (let [x (create m)
+        finished-channel (async/promise-chan)]
     (start x)
-    (wait x)
+    ;; timeout process
+    (async/go
+      (async/<! (async/timeout timeout))
+      (async/>! finished-channel {:timeout timeout
+                                  :done :timeout
+                                  :kill-container (kill-container x)}))
+    ;; watch the container
+    (async/go 
+      (wait x)
+      (async/>! finished-channel {:done :exited}))
+
     ;; body is raw PTY output
-    (let [s (:body (attach x))
+    (let [finish-reason (async/<!! finished-channel)
+          s (:body (attach x))
           info (inspect x)]
       (delete x)
-      {:pty-output s
-       :exit-code (-> info :State :ExitCode)
-       :info info})))
+      (merge
+        finish-reason
+        {:pty-output s
+         :exit-code (-> info :State :ExitCode)
+         :info info}))))
 
 (def extract-facts run-function)
 
@@ -279,10 +294,12 @@
             :host-dir "/Users/slim/docker/genai-stack"
             :user "jimclark106")) keyword))
   (docker/delete-image {:image "vonwig/go-linguist:latest"})
-  (extract-facts {:image "vonwig/go-linguist:latest"
-                  :command ["-json"]
-                  :host-dir "/Users/slim/docker/labs-make-runbook"
-                  :user "jimclark106"})
+  (pprint
+    (extract-facts {:image "vonwig/go-linguist:latest"
+                    :timeout 100
+                    :command ["-json"]
+                    :host-dir "/Users/slim/docker/labs-make-runbook"
+                    :user "jimclark106"}))
   (pprint
    (json/parse-string
     (extract-facts

src/markdown.clj

@@ -26,14 +26,17 @@
          (update 0 (fn [s] (.substring s (dec c1))))
          (update (dec (count lines)) (fn [s] (.substring s 0 (- c2 c1))))))))
 
-;; headings that include the word Prompt
-(defn prompt-section? [content node]
-  (string/includes?
-   (-> node (nth 2) (nth 3) (nth 1) (from-range content))
-   "Prompt"))
+(def prompt-pattern #"(?i)\s*prompt\s+(\w+)\s?")
 
 (defn extract-role [s]
-  (-> s (string/replace "Prompt" "") (string/trim)))
+  (second
+   (re-find prompt-pattern s)))
+
+;; headings that include the word Prompt
+(defn prompt-section? [content node]
+  (re-matches
+   prompt-pattern
+   (-> node (nth 2) (nth 3) (nth 1) (from-range content))))
 
 (defn remove-first-line [s]
   (->> (string/split s #"\n")
@@ -45,7 +48,7 @@
   {:role
    (-> node (nth 2) (nth 3) (nth 1) (from-range content) (extract-role))
    :content
-   (remove-first-line (from-range (nth node 1) content))} )
+   (remove-first-line (from-range (nth node 1) content))})
 
 (defn extract-prompts [content ast]
   (->>
@@ -57,7 +60,8 @@
    (map (partial node-content content))))
 
 (defn parse-markdown [content]
-  (let [x (docker/function-call-with-stdin
+  (let [content (str content "\n# END\n\n")
+        x (docker/function-call-with-stdin
            {:image "docker/lsp:treesitter"
             :content content})
         {s :pty-output} (async/<! (async/thread
@@ -71,7 +75,7 @@
 (comment
   (string/split content #"\n")
 
-  (def content (slurp "prompts/qrencode/README.md" ))
+  (def content (slurp "prompts/qrencode/README.md"))
   (pprint (parse-markdown content))
 
   (def t