Prompt: Educate about standalone use with llm program

CHANGES.md

@@ -1,6 +1,10 @@
 # About CrateDB changelog
 
 ## Unreleased
+- Prompt: Added `instructions-general.md` file when generating bundle
+- CLI: Added guidelines how to use the `llm` application and Python API
+  with `instructions-general.md` and `llms-full.txt` files for executing
+  prompts and holding conversations with LLMs.
 
 ## v0.0.6 - 2025-07-21
 - Prompt: Added instructions about working with CrateDB to be used for

README.md

@@ -60,13 +60,14 @@ nothing big.
 - The outline file [cratedb-outline.yaml] file indexes documents about
   what CrateDB is, what you can do with it, and how.
 
-- The Markdown file [cratedb-instructions.md] includes instructions and
+- The Markdown file [instructions.md] includes instructions and
   directives about how to use CrateDB. They can be used by humans as a
   cheat sheet, or to improve prompts for LLMs and similar technologies.
 
 - Context bundle files are published to the [about/v1] folder.
   They can be used to provide better context for conversations about
-  CrateDB, for example, by using the `cratedb-about ask` subcommand.
+  CrateDB, for example, by using the `cratedb-about ask` subcommand,
+  or by using generic applications like [`llm`].
 
 - The documentation subsystem of the [cratedb-mcp] package uses the
   Python API to serve and consider relevant documentation resources
@@ -167,22 +168,43 @@ also be specified using the `OUTDIR` environment variable.
 ### Query
 Ask questions about CrateDB from the command line.
 #### CLI
+Execute a prompt using the built-in Python implementation.
 ```shell
 export OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
 cratedb-about ask "CrateDB does not seem to provide an AUTOINCREMENT feature?"
 ```
+Hold an ongoing chat with a model using the versatile [`llm`] application.
+```shell
+uvx llm chat --model gpt-4.1 --option temperature 0.5 \
+  --fragment https://cdn.crate.io/about/v1/llms-full.txt \
+  --system-fragment https://cdn.crate.io/about/v1/instructions-general.md
+}
+```
 If you are running out of questions, get inspired by the standard library.
 ```shell
 cratedb-about list-questions
 ```
 #### API
-Use the Python API to ask questions about CrateDB.
+Use the built-in Python API to ask questions about CrateDB.
 ```python
 from cratedb_about import CrateDbKnowledgeConversation
 
 knowledge = CrateDbKnowledgeConversation()
 knowledge.ask("CrateDB does not seem to provide an AUTOINCREMENT feature?")
 ```
+Use the Python API of the `llm` package to ask questions about CrateDB.
+```python
+import llm
+
+model = llm.get_model("gpt-4.1")
+response = model.prompt(
+    "CrateDB does not seem to provide an AUTOINCREMENT feature?",
+    fragments=["https://cdn.crate.io/about/v1/llms-full.txt"],
+    system_fragments=["https://cdn.crate.io/about/v1/instructions-general.md"],
+    temperature=0.5,
+)
+print(response.text())
+```
 #### Notes
 - To configure a different context file, use the `ABOUT_CONTEXT_URL`
   environment variable. It can be a remote URL or a path on the local filesystem.
@@ -230,11 +252,12 @@ recommended, especially if you use it as a library.
 [about/v1]: https://cdn.crate.io/about/v1/
 [CrateDB]: https://cratedb.com/database
 [cratedb-about]: https://pypi.org/project/cratedb-about/
-[cratedb-instructions.md]: https://github.com/crate/about/blob/main/src/cratedb_about/instruction/cratedb-instructions.md
+[instructions.md]: https://github.com/crate/about/blob/main/src/cratedb_about/prompt/instructions.md
 [cratedb-mcp]: https://github.com/crate/cratedb-mcp
 [cratedb-outline.yaml]: https://github.com/crate/about/blob/main/src/cratedb_about/outline/cratedb-outline.yaml
 [filesystem-spec]: https://filesystem-spec.readthedocs.io/
 [hierarchical outline]: https://en.wikipedia.org/wiki/Outline_(list)
+[`llm`]: https://llm.datasette.io/
 [llms-txt]: https://llmstxt.org/
 [llms.txt]: https://cdn.crate.io/about/v1/llms.txt
 [llms-full.txt]: https://cdn.crate.io/about/v1/llms-full.txt

src/cratedb_about/bundle/readme.md

@@ -14,6 +14,7 @@ Target: <https://cdn.crate.io/about/v1/>
 - `outline.md`: The Markdown source file for generating the `llms.txt` file(s).
 - `llms.txt`: Output file `llms.txt` (standard).
 - `llms-full.txt`: Output file `llms.txt` (full), including the "Optional" section.
+- `instructions.md`: Instructions to be used within system prompts to LLMs.
 
 ## Details
 

src/cratedb_about/cli.py

@@ -7,6 +7,7 @@
 
 from cratedb_about.bundle.llmstxt import CrateDbLllmsTxtBuilder
 from cratedb_about.outline import CrateDbKnowledgeOutline
+from cratedb_about.prompt import GeneralInstructions
 from cratedb_about.query.core import CrateDbKnowledgeConversation
 from cratedb_about.query.model import Example
 
@@ -88,14 +89,18 @@ def outline(
 @click.pass_context
 def bundle(ctx: click.Context, url: str, format_: str, outdir: Path) -> None:
     """
-    Produce a context bundle from an outline file.
+    Produce files suitable to work with CrateDB and LLMs.
 
-    1. Generate multiple `llms.txt` files.
+    1. Produce a llms.txt context bundle file from an outline file.
+       Generate multiple `llms.txt` files.
        https://llmstxt.org/
+
+    2. Add `instructions-general.md` file.
     """
     if format_ != "llm":
         raise click.BadOptionUsage("format", f"Invalid output format: {format_}", ctx=ctx)
     CrateDbLllmsTxtBuilder(outline_url=url, outdir=outdir).run()
+    (outdir / "instructions-general.md").write_text(GeneralInstructions().render())
     logger.info("Ready.")
 
 

src/cratedb_about/instruction/__init__.py → src/cratedb_about/prompt/__init__.py

@@ -12,9 +12,7 @@ class GeneralInstructions:
     """  # noqa: E501
 
     def __init__(self):
-        instructions_file = (
-            importlib.resources.files("cratedb_about.instruction") / "cratedb-instructions.md"
-        )
+        instructions_file = importlib.resources.files("cratedb_about.prompt") / "instructions.md"
         self.instructions_text = instructions_file.read_text()
 
     def render(self) -> str:

tests/test_instructions.py → tests/test_prompt.py

@@ -1,4 +1,4 @@
-from cratedb_about.instruction import GeneralInstructions
+from cratedb_about.prompt import GeneralInstructions
 
 
 def test_instructions_full():