apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-07 07:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(readme): restructure for clarity and add FAQ + comparison table (#222)

Browse source 
* docs(readme): restructure for clarity and add FAQ + comparison table

Restructure the README: trim Common Commands to the 6 essentials and link
to the CLI Reference, add a "How ktx compares" table and "Who is ktx for"
qualifier, introduce a small FAQ, wrap key prompts in GitHub callouts,
merge the duplicate workspace-layout section into Development, move
Telemetry next to License, and add a Star History chart.

* docs(readme): tighten Skip-ktx list and convert FAQ to bullets
This commit is contained in:
Andrey Avtomonov 2026-05-26 14:10:12 +02:00
parent 62699bfe9d
commit 0eeac6f980
1 changed files with 116 additions and 100 deletions
Download patch file Download diff file Expand all files Collapse all files

216
README.md
View file

@ -16,17 +16,26 @@
<a href="https://www.ycombinator.com/companies?batch=P25"><img src="https://img.shields.io/badge/Y%20Combinator-P25-orange?style=flat-square" alt="Y Combinator P25" /></a> <a href="https://www.ycombinator.com/companies?batch=P25"><img src="https://img.shields.io/badge/Y%20Combinator-P25-orange?style=flat-square" alt="Y Combinator P25" /></a>
</p> </p>
<p align="center">
<a href="https://docs.kaelio.com/ktx/docs/getting-started/quickstart"><b>Quickstart</b></a> ·
<a href="https://docs.kaelio.com/ktx/docs/cli-reference/ktx"><b>CLI Reference</b></a> ·
<a href="https://docs.kaelio.com/ktx/docs/ai-resources/agent-quickstart"><b>Agent Setup</b></a> ·
<a href="https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ"><b>Slack</b></a>
</p>
--- ---
**ktx** is a self-improving context layer that teaches agents how to query your **ktx** is a self-improving context layer that teaches agents how to query your
warehouse accurately - from approved metric definitions, joinable columns, and warehouse accurately - from approved metric definitions, joinable columns, and
business knowledge it builds and maintains for you. business knowledge it builds and maintains for you.
Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and > [!NOTE]
SQLite. Integrates with dbt, MetricFlow, LookML, Looker, Metabase, and Notion. > Run **ktx** with your own LLM API keys or a **Claude Pro/Max** subscription.
> No extra usage billing from **ktx**.
Runs with your own LLM API keys or a **Claude <p align="center">
Pro/Max subscription - no extra usage billing from** **ktx**. <img src="docs-site/public/images/ingestion-flow-transparent.svg" alt="ktx ingestion flow from source systems through validation to wiki and semantic-layer outputs" width="900" />
</p>
## Why ktx ## Why ktx
@ -51,23 +60,35 @@ upkeep and don't absorb the rest of your company's knowledge.
- **Serves agents at execution.** Exposes CLI and MCP tools with combined - **Serves agents at execution.** Exposes CLI and MCP tools with combined
full-text and semantic search across wiki and semantic-layer entities. full-text and semantic search across wiki and semantic-layer entities.
Agents can run raw SQL when they need it, or compose semantic-layer queries ## How ktx compares
when they want approved metrics with reliable joins.
<p align="center"> | | General-purpose agent | Traditional semantic layer | **ktx** |
<img src="docs-site/public/images/ingestion-flow-transparent.svg" alt="ktx ingestion flow from source systems through validation to wiki and semantic-layer outputs" width="900" /> | --- | :---: | :---: | :---: |
</p> | Builds warehouse context automatically | — | — | ✓ |
| Detects joinable columns + resolves fan/chasm traps | — | Manual | ✓ |
| Approved, reusable metric definitions | — | ✓ | ✓ |
| Absorbs wiki / Notion / team knowledge | — | — | ✓ |
| Flags contradictions across sources | — | — | ✓ |
| Ships CLI + MCP for agent execution | Partial | — | ✓ |
| Read-only by design | n/a | n/a | ✓ |
## Agent Setup ## Who is ktx for
Ask an agent such as Claude Code, Codex, Cursor, or OpenCode to install and **Use ktx if you:**
configure **ktx** from your project directory:
```text - Want agents like Claude Code, Codex, Cursor, or OpenCode to query your
Follow instructions from warehouse with approved metric definitions
https://docs.kaelio.com/ktx/docs/agents-setup.md - Have business knowledge scattered across dbt, Looker, Metabase, Notion, and
to install and configure ktx team wikis
``` - Need agents to reuse canonical SQL instead of inventing it on every prompt
**Skip ktx if you:**
- You don't have a SQL warehouse - **ktx** sits on top of one
- You only need one ad-hoc query - `psql` or a notebook will do
Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and
SQLite. Integrates with dbt, MetricFlow, LookML, Looker, Metabase, and Notion.
## Quick Start ## Quick Start
@ -77,10 +98,10 @@ ktx setup
ktx status ktx status
``` ```
`ktx setup` creates or resumes a local **ktx** project, configures providers and `ktx setup` creates or resumes a local **ktx** project, configures providers
connections, builds context, and installs agent integration. and connections, builds context, and installs agent integration.
Example `ktx status` output after setup: Example `ktx status` after setup:
```text ```text
ktx project: /home/user/analytics ktx project: /home/user/analytics
@ -93,38 +114,33 @@ ktx context built: yes
Agent integration ready: yes (codex:project) Agent integration ready: yes (codex:project)
``` ```
## Telemetry > [!TIP]
> Already using an agent? Ask Claude Code, Codex, Cursor, or OpenCode from
> your project directory:
>
> ```text
> Follow instructions from
> https://docs.kaelio.com/ktx/docs/agents-setup.md
> to install and configure ktx
> ```
**ktx** collects anonymous usage telemetry from interactive CLI runs to improve > [!IMPORTANT]
setup, command reliability, and data-agent workflows. See > If `ktx status` prints `ktx mcp start --project-dir ...`, run it before
[Telemetry](https://docs.kaelio.com/ktx/docs/community/telemetry) for the event > opening your agent client.
catalog, privacy details, and opt-out options.
## Common Commands ## First commands
| Command | Purpose | | Command | Purpose |
|---------|---------| | --- | --- |
| `ktx setup` | Create, resume, or update a **ktx** project | | `ktx setup` | Create, resume, or update a **ktx** project |
| `ktx status` | Check project readiness | | `ktx status` | Check project readiness |
| `ktx connection` | List configured connections |
| `ktx connection test` | Test every configured connection |
| `ktx connection test <id>` | Test one connection |
| `ktx ingest` | Build context for every configured connection | | `ktx ingest` | Build context for every configured connection |
| `ktx ingest <id>` | Build context for one connection |
| `ktx ingest --text "..."` | Capture free-form notes into memory |
| `ktx ingest --file notes.md --connection-id <id>` | Capture a text file into memory |
| `ktx sl` | List semantic sources |
| `ktx sl "revenue"` | Search semantic sources | | `ktx sl "revenue"` | Search semantic sources |
| `ktx sl validate <source> --connection-id <id>` | Validate a semantic source | | `ktx wiki "refund policy"` | Search local wiki pages |
| `ktx sl query --measure <measure> --format sql` | Compile semantic-layer SQL | | `ktx mcp start` | Start the MCP server for agent clients |
| `ktx sql --connection <id> "select 1"` | Execute read-only SQL |
| `ktx wiki` | List local wiki pages |
| `ktx wiki "revenue definition"` | Search local wiki pages |
| `ktx mcp` | Show MCP daemon status |
| `ktx mcp start` | Start the local MCP server for agent clients |
Project resolution defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, See the [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
then the current directory. Pass `--project-dir <path>` when scripting. for every command, flag, and option.
## Project Layout ## Project Layout
@ -140,46 +156,43 @@ my-project/
Commit `ktx.yaml`, `semantic-layer/`, and `wiki/`. Keep `.ktx/` local. Commit `ktx.yaml`, `semantic-layer/`, and `wiki/`. Keep `.ktx/` local.
## Agent Usage Project resolution defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`,
then the current directory. Pass `--project-dir <path>` when scripting.
Install **ktx** integration for Claude Code, Claude Desktop, Codex, Cursor, ## FAQ
OpenCode, and generic `.agents` clients:
```bash - **Does ktx send my schema or query results to a hosted service?**
ktx setup --agents No. **ktx** runs locally. The only data leaving your machine is what you
``` send to the LLM provider you configured.
- **Which LLM backends are supported?**
Anthropic API, Google Vertex AI, AI Gateway, and the local Claude Code
session through the Claude Agent SDK. See
[LLM configuration](https://docs.kaelio.com/ktx/docs/guides/llm-configuration).
- **How is ktx different from a dbt or MetricFlow semantic layer?**
**ktx** *ingests* those layers and combines them with raw-table
introspection and wiki content. Agents get one searchable surface instead
of three disconnected ones - and **ktx** flags contradictions across
sources.
- **Does ktx need a running server?**
There is no hosted service. The local MCP daemon runs on demand via
`ktx mcp start` when an agent client needs it.
- **Is my warehouse safe?**
Yes. Connections are read-only - **ktx** never writes to your database.
Pass `--target <target>` to install or repair one specific integration. ## Docs
A typical agent workflow combines wiki and semantic-layer search before - [Quickstart](https://docs.kaelio.com/ktx/docs/getting-started/quickstart)
querying: - [The Context Layer](https://docs.kaelio.com/ktx/docs/concepts/the-context-layer)
- [Building Context](https://docs.kaelio.com/ktx/docs/guides/building-context)
- [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
- [Agent Quickstart](https://docs.kaelio.com/ktx/docs/ai-resources/agent-quickstart)
- [Community & Support](https://docs.kaelio.com/ktx/docs/community/support)
```bash ## Community
ktx sl "revenue" --json
ktx wiki "refund policy" --json
ktx sl query --connection-id warehouse --measure orders.revenue --format sql
```
During setup, choose **Ask data questions with ktx MCP** for agent clients. - **[Slack](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ)** — ask questions, share what you're building, and chat with maintainers.
Choose **Ask data questions + manage ktx with CLI commands** when an operator - **[GitHub Issues](https://github.com/Kaelio/ktx/issues)** — report bugs and request features.
agent also needs pinned `ktx` admin commands. Choose **Skip agent setup for - **[Contributing](https://docs.kaelio.com/ktx/docs/community/contributing)** — set up the repo, run tests, and open a PR.
now** to leave agent integration incomplete and run `ktx setup --agents` later.
After setup, **ktx** prints **Required before using agents** with the exact
commands to run. If the output includes `ktx mcp start --project-dir ...`, run
it before opening your agent. Claude Desktop gets a stdio MCP config entry and
prints separate skill upload steps under `.ktx/agents/claude/`.
## Workspace layout
| Path | Purpose |
|------|---------|
| `packages/cli` | TypeScript CLI package and published npm package source |
| `packages/cli/src/context` | Core context engine |
| `packages/cli/src/llm` | LLM and embedding providers |
| `packages/cli/src/connectors` | Database scan connectors |
| `python/ktx-sl` | Semantic-layer query planning |
| `python/ktx-daemon` | Portable compute service |
## Development ## Development
@ -192,7 +205,18 @@ pnpm run build
pnpm run check pnpm run check
``` ```
Use the development CLI locally: **ktx** is a pnpm + uv workspace:
| Path | Purpose |
| --- | --- |
| `packages/cli` | TypeScript CLI and published npm package source |
| `packages/cli/src/context` | Core context engine |
| `packages/cli/src/llm` | LLM and embedding providers |
| `packages/cli/src/connectors` | Database scan connectors |
| `python/ktx-sl` | Semantic-layer query planning |
| `python/ktx-daemon` | Portable compute service |
Local development CLI:
```bash ```bash
pnpm run setup:dev pnpm run setup:dev
@ -200,13 +224,6 @@ pnpm run link:dev
ktx-dev --help ktx-dev --help
``` ```
**ktx** is a pnpm + uv workspace:
- TypeScript packages live in `packages/*`
- CLI source lives in `packages/cli`
- Python runtime source lives in `python/ktx-sl` and `python/ktx-daemon`
- Public docs live in `docs-site/content/docs`
Useful checks: Useful checks:
```bash ```bash
@ -216,23 +233,22 @@ pnpm run dead-code
uv run pytest -q uv run pytest -q
``` ```
## Docs ## Telemetry
- [Quickstart](docs-site/content/docs/getting-started/quickstart.mdx) **ktx** collects anonymous usage telemetry from interactive CLI runs to
- [CLI Reference](docs-site/content/docs/cli-reference/ktx.mdx) improve setup, command reliability, and data-agent workflows. No file paths,
- [Building Context](docs-site/content/docs/guides/building-context.mdx) hostnames, SQL, schema names, error messages, or argv are recorded. See
- [Community & Support](docs-site/content/docs/community/support.mdx) [Telemetry](https://docs.kaelio.com/ktx/docs/community/telemetry) for the
- [Contributing](docs-site/content/docs/community/contributing.mdx) event catalog and opt-out options.
## Community
- **[Slack](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ)** — ask questions, share what you're building, and chat with maintainers and other users.
- **[GitHub Issues](https://github.com/Kaelio/ktx/issues)** — report bugs and request features.
- **[Contributing guide](docs-site/content/docs/community/contributing.mdx)** — set up the repo, run tests, and open a PR.
See [Community & Support](docs-site/content/docs/community/support.mdx) for the
full guide on where to ask what.
## License ## License
**ktx** is licensed under the Apache License, Version 2.0. See `LICENSE`. **ktx** is licensed under the Apache License, Version 2.0. See `LICENSE`.
## Star History
<p align="center">
<a href="https://star-history.com/#Kaelio/ktx&Date">
<img src="https://api.star-history.com/svg?repos=Kaelio/ktx&type=Date" alt="ktx Star History Chart" width="700" />
</a>
</p>