diff --git a/CHANGES.md b/CHANGES.md index 6d88eb0..0a344b9 100644 --- a/CHANGES.md +++ b/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 diff --git a/README.md b/README.md index 4074302..dd34b09 100644 --- a/README.md +++ b/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= 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 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/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.") 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():