From 83d25ef3dd703363c7bd9c3af4500eeee2954dcc Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 11 May 2025 13:17:18 +0200 Subject: [PATCH 1/4] README: Add a few elaborations and refinements --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 56 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index aeafb8c..66ff938 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,14 @@ # About CrateDB -[![Bluesky][badge-bluesky]][project-bluesky] - +[![Status][badge-status]][project-pypi] [![CI][badge-ci]][project-ci] [![Coverage][badge-coverage]][project-coverage] +[![Downloads per month][badge-downloads-per-month]][project-downloads] + [![License][badge-license]][project-license] [![Release Notes][badge-release-notes]][project-release-notes] - -[![Status][badge-status]][project-pypi] [![PyPI Version][badge-package-version]][project-pypi] [![Python Versions][badge-python-versions]][project-pypi] -[![Downloads per month][badge-downloads-per-month]][project-downloads] ยป [Documentation] | [Releases] @@ -19,6 +17,7 @@ | [License] | [CrateDB] | [Community Forum] +| [Bluesky] A high-level description about [CrateDB], with cross-references to relevant resources in the spirit of a curated knowledge backbone. @@ -30,17 +29,46 @@ to relevant resources in the spirit of a curated knowledge backbone. ## What's inside -- A few tidbits of _structured docs_. +### Abstract + +- A few tidbits of _structured docs_ along the idea of a + basic and generic [hierarchical outline]. + +- Utility programs that read outline files in [YAML] format and produce + output files or packages by expanding all links, for example, into + [Markdown] or [llms.txt] formats, supporting the authoring and + production process. -- The [cratedb-outline.yaml] file indexes documents about what CrateDB is - and what you can do with it. +- A compact Python API that offers selective access to documentation + and knowledge resources by providing basic querying primitives to + inquire elements within the outline tree. + The API can be used by a [Model Context Protocol (MCP)] documentation + server to acquire information about the relevant topic domain on demand. -- The [about/v1] folder includes [llms.txt] files generated from - [cratedb-outline.yaml] by expanding all links. They can be used - to provide better context for conversations about CrateDB. +### Applied + +- The outline file [cratedb-outline.yaml] file indexes documents about + what CrateDB is, what you can do with it, and how. + +- Output files are produced to the [about/v1] folder. + They can be used to provide better context for conversations about + CrateDB. + +- The `cratedb-about ask` subcommand uses those context files to answer + questions about CrateDB that would otherwise yield incomprehensible, + incomplete, or weak responses. + +- The documentation subsystem of the [cratedb-mcp] package uses the + Python API to serve and consider relevant documentation resources + within its data flow procedures. It selects relevant resources mostly + based on the value of the `description` attribute of the outline + data model. ## Install +The authors recommend using the [uv] package manager. Alternative +options are to use `pipx` or `pip install --user`. + ### From PyPI ```shell uv tool install --upgrade 'cratedb-about[all]' @@ -52,6 +80,12 @@ uv tool install --upgrade 'cratedb-about[all] @ git+https://github.com/crate/abo ## Usage +The program provides three subsystems. + +- Outline: Read and inquire outline files. +- Build: Produce context output bundles from outline files. +- Query: Use context information for conversations with LLMs. + ### Outline #### CLI @@ -72,8 +106,6 @@ environment variable. #### API Use the Python API to retrieve individual sets of outline items, for example, by section name. The standard section names are: Docs, API, Examples, Optional. -The API can be used to feed information to a [Model Context Protocol (MCP)] -documentation server, for example, a subsystem of [cratedb-mcp]. ```python from cratedb_about import CrateDbKnowledgeOutline @@ -140,7 +172,12 @@ this project is building upon. ### Contributing The `cratedb-about` package is an open source project, and is [managed on -GitHub]. Contributions of any kind are very much appreciated. +GitHub]. Contributions of any kind are very much welcome and always +appreciated. + +### Status +The software is in the planning/pre-alpha stage. Version pinning is strongly +recommended, especially if you use it as a library. [about/v1]: https://cdn.crate.io/about/v1/ @@ -148,9 +185,14 @@ GitHub]. Contributions of any kind are very much appreciated. [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) [llms.txt]: https://llmstxt.org/ +[Markdown]: https://daringfireball.net/projects/markdown/ [Model Context Protocol (MCP)]: https://modelcontextprotocol.io/introduction +[uv]: https://docs.astral.sh/uv/ +[YAML]: https://en.wikipedia.org/wiki/Yaml +[Bluesky]: https://bsky.app/search?q=cratedb [Community Forum]: https://community.cratedb.com/ [Documentation]: https://github.com/crate/about [Issues]: https://github.com/crate/about/issues @@ -159,7 +201,6 @@ GitHub]. Contributions of any kind are very much appreciated. [Source code]: https://github.com/crate/about [Releases]: https://github.com/crate/about/releases -[badge-bluesky]: https://img.shields.io/badge/Bluesky-0285FF?logo=bluesky&logoColor=fff&label=Follow%20%40CrateDB [badge-ci]: https://github.com/crate/about/actions/workflows/tests.yml/badge.svg [badge-coverage]: https://codecov.io/gh/crate/about/branch/main/graph/badge.svg [badge-downloads-per-month]: https://pepy.tech/badge/cratedb-about/month @@ -168,7 +209,6 @@ GitHub]. Contributions of any kind are very much appreciated. [badge-python-versions]: https://img.shields.io/pypi/pyversions/cratedb-about.svg [badge-release-notes]: https://img.shields.io/github/release/crate/about?label=Release+Notes [badge-status]: https://img.shields.io/pypi/status/cratedb-about.svg -[project-bluesky]: https://bsky.app/search?q=cratedb [project-ci]: https://github.com/crate/about/actions/workflows/tests.yml [project-coverage]: https://app.codecov.io/gh/crate/about [project-downloads]: https://pepy.tech/project/cratedb-about/ From 5537e9933f2bb54a25dd566a7520ed4c36ed7d87 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 11 May 2025 13:37:45 +0200 Subject: [PATCH 2/4] README: Address suggestions by CodeRabbit --- README.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 66ff938..70bd6e4 100644 --- a/README.md +++ b/README.md @@ -31,32 +31,33 @@ to relevant resources in the spirit of a curated knowledge backbone. ### Abstract -- A few tidbits of _structured docs_ along the idea of a - basic and generic [hierarchical outline]. +- Structured documentation based on a generic [hierarchical outline]. -- Utility programs that read outline files in [YAML] format and produce - output files or packages by expanding all links, for example, into - [Markdown] or [llms.txt] formats, supporting the authoring and +- Utility programs to parse [YAML] outline files and generate outputs + (e.g., [Markdown], [llms.txt]), supporting the authoring and production process. - A compact Python API that offers selective access to documentation and knowledge resources by providing basic querying primitives to inquire elements within the outline tree. - The API can be used by a [Model Context Protocol (MCP)] documentation - server to acquire information about the relevant topic domain on demand. ### Applied +- The `ask` subcommand uses [llms.txt] context files to answer questions + about a topic domain that would otherwise yield incomprehensible, + incomplete, or weak responses. + +- The Python API can be used by a [Model Context Protocol (MCP)] documentation + server to acquire information about the relevant topic domain on demand. + +### Concrete + - The outline file [cratedb-outline.yaml] file indexes documents about what CrateDB is, what you can do with it, and how. -- Output files are produced to the [about/v1] folder. +- Context bundle files are published to the [about/v1] folder. They can be used to provide better context for conversations about - CrateDB. - -- The `cratedb-about ask` subcommand uses those context files to answer - questions about CrateDB that would otherwise yield incomprehensible, - incomplete, or weak responses. + CrateDB, for example, by using the `cratedb-about ask` subcommand. - The documentation subsystem of the [cratedb-mcp] package uses the Python API to serve and consider relevant documentation resources @@ -80,7 +81,7 @@ uv tool install --upgrade 'cratedb-about[all] @ git+https://github.com/crate/abo ## Usage -The program provides three subsystems. +The `cratedb-about` package provides three subsystems. - Outline: Read and inquire outline files. - Build: Produce context output bundles from outline files. @@ -172,11 +173,10 @@ this project is building upon. ### Contributing The `cratedb-about` package is an open source project, and is [managed on -GitHub]. Contributions of any kind are very much welcome and always -appreciated. +GitHub]. Contributions of any kind are welcome and appreciated. ### Status -The software is in the planning/pre-alpha stage. Version pinning is strongly +The software is in the pre-alpha (planning) stage. Version pinning is strongly recommended, especially if you use it as a library. From 47f296e2998832b732cc10ba78d7080c5e970335 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 11 May 2025 15:55:37 +0200 Subject: [PATCH 3/4] README: Improve "What's inside" section --- README.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 70bd6e4..9d92124 100644 --- a/README.md +++ b/README.md @@ -29,26 +29,31 @@ to relevant resources in the spirit of a curated knowledge backbone. ## What's inside +A workbench rig for information and knowledge management, +aiming to compress content authoring and curation processes, +nothing big. + ### Abstract -- Structured documentation based on a generic [hierarchical outline]. +- **Structured documentation** based on a basic and generic [hierarchical outline]. -- Utility programs to parse [YAML] outline files and generate outputs - (e.g., [Markdown], [llms.txt]), supporting the authoring and +- **Utility programs** to parse [YAML] outline files and generate outputs + (e.g., [Markdown], [llms-txt]), supporting the authoring and production process. -- A compact Python API that offers selective access to documentation +- **Python API** that offers selective access to documentation and knowledge resources by providing basic querying primitives to - inquire elements within the outline tree. + inquire elements from the outline tree. ### Applied -- The `ask` subcommand uses [llms.txt] context files to answer questions +- The `ask` subcommand uses [llms-txt] context files to answer questions about a topic domain that would otherwise yield incomprehensible, incomplete, or weak responses. -- The Python API can be used by a [Model Context Protocol (MCP)] documentation - server to acquire information about the relevant topic domain on demand. +- The compact Python API can be used by a [Model Context Protocol (MCP)] + documentation server to acquire information about the relevant topic + domain on demand. ### Concrete @@ -186,7 +191,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) -[llms.txt]: https://llmstxt.org/ +[llms-txt]: https://llmstxt.org/ [Markdown]: https://daringfireball.net/projects/markdown/ [Model Context Protocol (MCP)]: https://modelcontextprotocol.io/introduction [uv]: https://docs.astral.sh/uv/ From 798102096ae9e3f1a902a5911c8fb08a38016e61 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Sun, 11 May 2025 15:56:22 +0200 Subject: [PATCH 4/4] README: Add "FAQ" section --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index 9d92124..580333b 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,26 @@ cratedb-about list-questions To configure a different context file, use the `CRATEDB_CONTEXT_URL` environment variable. The default value is https://cdn.crate.io/about/v1/llms-full.txt. +## FAQ + +- Q: Seriously, how do I use this? + + A: As mentioned above, this repository includes content and a few utilities + to manage corresponding information. Users will directly use the produced + [llms.txt] and [llms-full.txt] files. Developers will install the [cratedb-about] + package to access fundamental outline information in their own programs + programmatically, or to invoke fragments of the production machinery + on their premises, either ad hoc, or by including it in automated pipelines. + +- Q: It looks like the knowledge base machinery is missing important information + about CrateDB. I've asked it about matters of polymer sharding, and the answer + wasn't very insightful. + + A: Well, we can understand your disappointment. To improve the situation, + we are constantly curating content, and you can support the process by giving + us hints about which fragments of information to include in the set of + curated information. To learn about what this means, see also [ABOUT-24]. + ## Project Information ### Acknowledgements @@ -185,13 +205,17 @@ The software is in the pre-alpha (planning) stage. Version pinning is strongly recommended, especially if you use it as a library. +[ABOUT-24]: https://github.com/crate/about/issues/24 [about/v1]: https://cdn.crate.io/about/v1/ [CrateDB]: https://cratedb.com/database +[cratedb-about]: https://pypi.org/project/cratedb-about/ [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) [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 [Markdown]: https://daringfireball.net/projects/markdown/ [Model Context Protocol (MCP)]: https://modelcontextprotocol.io/introduction [uv]: https://docs.astral.sh/uv/