From 29125f1ac0189a85085da2ba7fdb9561b04efad7 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Tue, 22 Jul 2025 00:16:34 +0200 Subject: [PATCH 1/3] Prompt: Refactor / naming things - s/cratedb_about.instruction/cratedb_about.prompt/ - s/cratedb-instructions.md/instructions.md/ --- README.md | 4 ++-- src/cratedb_about/bundle/readme.md | 1 + src/cratedb_about/{instruction => prompt}/__init__.py | 4 +--- .../cratedb-instructions.md => prompt/instructions.md} | 0 tests/{test_instructions.py => test_prompt.py} | 2 +- 5 files changed, 5 insertions(+), 6 deletions(-) rename src/cratedb_about/{instruction => prompt}/__init__.py (86%) rename src/cratedb_about/{instruction/cratedb-instructions.md => prompt/instructions.md} (100%) rename tests/{test_instructions.py => test_prompt.py} (83%) diff --git a/README.md b/README.md index 4074302..30db6a1 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ 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. @@ -230,7 +230,7 @@ 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/ diff --git a/src/cratedb_about/bundle/readme.md b/src/cratedb_about/bundle/readme.md index e04dd3a..fab034f 100644 --- a/src/cratedb_about/bundle/readme.md +++ b/src/cratedb_about/bundle/readme.md @@ -14,6 +14,7 @@ Target: - `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 diff --git a/src/cratedb_about/instruction/__init__.py b/src/cratedb_about/prompt/__init__.py similarity index 86% rename from src/cratedb_about/instruction/__init__.py rename to src/cratedb_about/prompt/__init__.py index 02434a5..0552b16 100644 --- a/src/cratedb_about/instruction/__init__.py +++ b/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: diff --git a/src/cratedb_about/instruction/cratedb-instructions.md b/src/cratedb_about/prompt/instructions.md similarity index 100% rename from src/cratedb_about/instruction/cratedb-instructions.md rename to src/cratedb_about/prompt/instructions.md diff --git a/tests/test_instructions.py b/tests/test_prompt.py similarity index 83% rename from tests/test_instructions.py rename to tests/test_prompt.py index f712e41..a27add9 100644 --- a/tests/test_instructions.py +++ b/tests/test_prompt.py @@ -1,4 +1,4 @@ -from cratedb_about.instruction import GeneralInstructions +from cratedb_about.prompt import GeneralInstructions def test_instructions_full(): From 802f97ef348be328786d4a6ba655f0d5d37847da Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Tue, 22 Jul 2025 00:17:45 +0200 Subject: [PATCH 2/3] Prompt: Add `instructions-general.md` file when generating bundle --- CHANGES.md | 1 + src/cratedb_about/cli.py | 9 +++++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 6d88eb0..81b0446 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,7 @@ # About CrateDB changelog ## Unreleased +- Prompt: Added `instructions-general.md` file when generating bundle ## v0.0.6 - 2025-07-21 - Prompt: Added instructions about working with CrateDB to be used for diff --git a/src/cratedb_about/cli.py b/src/cratedb_about/cli.py index 97fc5f8..0384171 100644 --- a/src/cratedb_about/cli.py +++ b/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.") From 4174ee7dff8335e1414d90cff97209967b5ebc9f Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Tue, 22 Jul 2025 01:48:27 +0200 Subject: [PATCH 3/3] CLI: Add 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. --- CHANGES.md | 3 +++ README.md | 27 +++++++++++++++++++++++++-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 81b0446..0a344b9 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,9 @@ ## 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 diff --git a/README.md b/README.md index 30db6a1..dd34b09 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,8 @@ nothing big. - 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= 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. @@ -235,6 +257,7 @@ recommended, especially if you use it as a library. [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