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

feat(cli): smart defaults and flatter command surface for ktx (#177)

Browse source 
Bare invocations now do the obvious thing instead of erroring out, and mode-as-subcommand patterns collapse into flags on the parent. No new top-level commands.

- `ktx ingest` (bare) ingests every configured connection. The `text` subcommand is gone; capture inline notes with `ktx ingest --text "..."` and files with `ktx ingest --file path` (use `-` for stdin). `--text`/`--file` reject a positional connection id; pass `--connection-id` to tag captured notes.
- `ktx connection` (bare) lists; `ktx connection test` (bare) tests every configured connection.
- `ktx wiki` and `ktx sl` flatten `list`/`search`: bare lists, with a `[query...]` positional searches (multi-word joined with spaces). `sl validate` and `sl query` stay as distinct verbs and now read `--connection-id` from the parent.
- `ktx mcp` (bare) prints daemon status.

Adds a shared `resolveConnectionSelection` helper consumed by ingest and connection test. Updates README, docs-site cli-reference and guides, next-steps strings, agent SKILL templates, and all affected tests. Per-package type-check, unit tests (605), smoke tests, and dead-code checks all pass.
This commit is contained in:
Andrey Avtomonov 2026-05-20 01:52:37 +02:00 • committed by GitHub
parent 14626c294b
commit 2c9a58bb56
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
33 changed files with 438 additions and 380 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs-site/content/docs/guides/building-context.mdx
View file

@ -106,28 +106,30 @@ edits.
## Text ingest
Use `ktx ingest text` for notes, Markdown, runbooks, Slack exports, or other
searchable memory.
Use `ktx ingest --text` / `ktx ingest --file` for notes, Markdown, runbooks,
Slack exports, or other searchable memory.
```bash
# Capture a Markdown file
ktx ingest text docs/revenue-notes.md --connection-id warehouse
ktx ingest --file docs/revenue-notes.md --connection-id warehouse
# Capture one stdin item
printf "Refunds are excluded from net revenue." | ktx ingest text -
printf "Refunds are excluded from net revenue." | ktx ingest --file -
# Capture direct text
ktx ingest text --text "ARR excludes one-time implementation fees."
ktx ingest --text "ARR excludes one-time implementation fees."
```
Useful flags:
| Flag | Description |
|------|-------------|
| `--text <content>` | Capture inline text into memory; repeatable |
| `--file <path>` | Capture a text file (or `-` for stdin) into memory; repeatable |
| `--connection-id <connectionId>` | Attach the captured memory to a KTX connection |
| `--user-id <id>` | Attribute capture to a user scope, default `local-cli` |
| `--json` | Print structured output |
| `--fail-fast` | Stop after the first failed text item |
| `--fail-fast` | Stop after the first failed text/file item |
Use text ingest for small, high-signal documents. Prefer configured source
ingest for Notion, dbt, Metabase, and similar systems.
@ -165,8 +167,8 @@ Then inspect what changed:
```bash
git status --short
ktx sl list --json
ktx wiki search "revenue" --json --limit 10
ktx sl --json
ktx wiki "revenue" --json --limit 10
```
## Common errors
@ -176,6 +178,6 @@ ktx wiki search "revenue" --json --limit 10
| Connection not configured | The connection id is missing from `ktx.yaml` | Add it with `ktx setup` |
| Deep readiness is missing | LLM or embeddings are not setup-ready | Run `ktx setup`, or rerun with `--fast` |
| Query history is unsupported | The selected database driver does not expose query history | Run schema ingest without query-history flags |
| No target selected | You omitted both a connection id and `--all` | Run `ktx ingest <connectionId>` or `ktx ingest --all` |
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
| Source flags have no effect | Depth and query-history flags were supplied for a source connector | Use those flags only for database connections |
| Text ingest stops early | `--fail-fast` stopped on the first failed item | Fix the item or rerun without `--fail-fast` |

18
docs-site/content/docs/guides/serving-agents.mdx
View file

@ -58,9 +58,9 @@ context-build, and agent-integration readiness.
### Semantic layer discovery
```bash
ktx sl list --json
ktx sl list --connection-id warehouse --json
ktx sl search "revenue" --json --limit 10
ktx sl --json
ktx sl --connection-id warehouse --json
ktx sl "revenue" --json --limit 10
```
Use these commands to find source names, connection ids, measures, dimensions,
@ -99,8 +99,8 @@ For complex calls, agents can write a JSON query object and pass it with
### Wiki context
```bash
ktx wiki list --json
ktx wiki search "revenue recognition" --json --limit 10
ktx wiki --json
ktx wiki "revenue recognition" --json --limit 10
```
Search wiki context for business definitions, metric caveats, process rules, and
@ -112,8 +112,8 @@ Agents can refresh context when the user asks them to:
```bash
ktx ingest warehouse --fast
ktx ingest --all
ktx ingest text docs/revenue-notes.md --connection-id warehouse
ktx ingest
ktx ingest --file docs/revenue-notes.md --connection-id warehouse
```
Use `--deep` only when LLM and embedding setup is ready.
@ -123,7 +123,7 @@ Use `--deep` only when LLM and embedding setup is ready.
Agents should:
- Run `ktx status --json` before using KTX context.
- Use `ktx sl search` and `ktx wiki search` before writing SQL from memory.
- Use `ktx sl <query>` and `ktx wiki <query>` before writing SQL from memory.
- Inspect the relevant YAML or Markdown files after search returns candidates.
- Compile SQL with `ktx sl query --format sql` before executing.
- Use `--max-rows` whenever executing a live query.
@ -156,5 +156,5 @@ For per-client notes, see [Agent Clients](/docs/integrations/agent-clients).
| Agent says KTX is unavailable | Agent did not load the generated instruction file | Rerun `ktx setup --agents --target <target>` and restart the agent session |
| Agent command cannot find the project | Agent is running outside the KTX directory | Add `--project-dir <path>` or open the agent in the project root |
| Generated rules point at a missing CLI path | CLI was moved, rebuilt, or reinstalled | Rerun `ktx setup --agents` |
| Agent cannot find a metric | Context is missing or stale | Run `ktx sl search`, inspect source YAML, then refresh with `ktx ingest` if needed |
| Agent cannot find a metric | Context is missing or stale | Run `ktx sl <query>`, inspect source YAML, then refresh with `ktx ingest` if needed |
| Agent query returns too many rows | The command executed without a result cap | Require `--max-rows` for executed queries |

12
docs-site/content/docs/guides/writing-context.mdx
View file

@ -13,9 +13,9 @@ Use this order for most context changes:
1. Discover existing context.
```bash
ktx sl list --json
ktx sl search "revenue" --json
ktx wiki search "revenue recognition" --json --limit 10
ktx sl --json
ktx sl "revenue" --json
ktx wiki "revenue recognition" --json --limit 10
```
2. Edit the smallest relevant files under `semantic-layer/<connection-id>/` or
@ -306,7 +306,7 @@ Useful frontmatter:
1. Search first.
```bash
ktx wiki search "active customer definition" --json --limit 10
ktx wiki "active customer definition" --json --limit 10
```
2. If no page covers the rule, create or edit a Markdown file under
@ -323,8 +323,8 @@ Before accepting agent-written context:
```bash
git diff -- semantic-layer wiki
ktx sl validate orders --connection-id warehouse
ktx sl search "revenue" --json
ktx wiki search "revenue recognition" --json --limit 10
ktx sl "revenue" --json
ktx wiki "revenue recognition" --json --limit 10
```
Check definitions, hidden columns, join relationships, and generated SQL.