mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-16 08:25:14 +02:00
docs: standardize ktx naming (#187)
* docs: align KTX terminology * docs: standardize ktx naming
This commit is contained in:
Andrey Avtomonov
GitHub
parent
2f70861a18
commit
17647a436a
43 changed files with 438 additions and 419 deletions
|
|
@ -19,9 +19,9 @@ ktx admin <subcommand> [options]
|
|||
|
||||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `init [directory]` | Initialize a Git-backed KTX project directory for maintenance scripts |
|
||||
| `init [directory]` | Initialize a Git-backed **ktx** project directory for maintenance scripts |
|
||||
| `schema` | Print a JSON Schema describing `ktx.yaml` |
|
||||
| `runtime` | Install, start, stop, and inspect the KTX-managed Python runtime |
|
||||
| `runtime` | Install, start, stop, and inspect the **ktx**-managed Python runtime |
|
||||
| `reindex` | Sync local wiki and semantic-layer search indexes from disk |
|
||||
|
||||
## `admin init`
|
||||
|
|
@ -44,8 +44,8 @@ directory. Use it from any directory to generate editor or agent schema files.
|
|||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `install` | Install the bundled Python runtime wheel into the managed runtime |
|
||||
| `start` | Start the KTX daemon |
|
||||
| `stop` | Stop the KTX daemon |
|
||||
| `start` | Start the **ktx** daemon |
|
||||
| `stop` | Stop the **ktx** daemon |
|
||||
| `status` | Show managed Python runtime status and readiness checks |
|
||||
|
||||
## `admin runtime` Options
|
||||
|
|
@ -56,7 +56,7 @@ directory. Use it from any directory to generate editor or agent schema files.
|
|||
| `--json` | Print JSON output for `status` | `false` |
|
||||
| `--yes` | Accepted by `install` for scripted install commands | `false` |
|
||||
| `--force` | Reinstall for `install`, or restart for `start` | `false` |
|
||||
| `--all` | Stop all recorded or discoverable KTX daemon processes with `stop` | `false` |
|
||||
| `--all` | Stop all recorded or discoverable **ktx** daemon processes with `stop` | `false` |
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
@ -102,15 +102,15 @@ ktx admin reindex --output plain
|
|||
ktx admin reindex --json
|
||||
```
|
||||
|
||||
By default, KTX compares stored search text with the files on disk. It only
|
||||
By default, **ktx** compares stored search text with the files on disk. It only
|
||||
re-embeds changed rows and removes rows for files that no longer exist. With
|
||||
`--force`, KTX clears each discovered scope first and then rebuilds it.
|
||||
`--force`, **ktx** clears each discovered scope first and then rebuilds it.
|
||||
|
||||
When embeddings are not configured, KTX still writes lexical FTS rows and
|
||||
prints an embeddings warning. If a scope fails, KTX keeps processing the
|
||||
When embeddings are not configured, **ktx** still writes lexical FTS rows and
|
||||
prints an embeddings warning. If a scope fails, **ktx** keeps processing the
|
||||
remaining scopes and exits with code `1` after output is written. If the local
|
||||
state database cannot open or the configured managed embedding runtime is
|
||||
missing, KTX prints the error and exits with code `1`.
|
||||
missing, **ktx** prints the error and exits with code `1`.
|
||||
|
||||
## Common errors
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,12 @@
|
|||
---
|
||||
title: "ktx connection"
|
||||
description: "List and test configured data sources."
|
||||
description: "List and test configured database and context-source connections."
|
||||
---
|
||||
|
||||
Inspect configured connections in your KTX project. Connections define how KTX
|
||||
reaches databases, warehouses, BI tools, source projects, and knowledge
|
||||
systems. Use `ktx setup` to add, remove, or reconfigure them.
|
||||
Inspect configured connections in your **ktx** project. Connections define how **ktx**
|
||||
reaches primary sources (databases and warehouses) and context sources (BI
|
||||
tools, modeling projects, and knowledge systems). Use `ktx setup` to add,
|
||||
remove, or reconfigure them.
|
||||
|
||||
## Command signature
|
||||
|
||||
|
|
@ -77,8 +78,8 @@ my-warehouse postgres
|
|||
|
||||
`ktx connection test <connectionId>` performs a lightweight connection probe.
|
||||
Native database connections report `Status: ok` when the connector probe
|
||||
passes. Source connectors report connector-specific details such as Metabase
|
||||
database count, Looker user, Notion bot, or Git repo URL.
|
||||
passes. Context-source connectors report connector-specific details such as
|
||||
Metabase database count, Looker user, Notion bot, or Git repo URL.
|
||||
|
||||
```text
|
||||
Connection test passed: my-warehouse
|
||||
|
|
@ -102,7 +103,7 @@ configured connection and exit non-zero if any probe fails.
|
|||
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or source connection |
|
||||
| No connections configured | The project has no entries under `connections` | Run `ktx setup` and add a database or context-source connection |
|
||||
| Connection test fails | Credentials, network access, database, warehouse, or schema is invalid | Verify the same URL with the database's native client, then rerun `ktx setup` and reconfigure the connection |
|
||||
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the source mapping selections |
|
||||
| Mapping validation fails during setup | BI database mappings do not point at valid warehouse connections | Rerun `ktx setup` and update the context-source mapping selections |
|
||||
| Notion page picker cannot run | The terminal is non-interactive or Notion discovery failed | Rerun interactive `ktx setup`, or use non-interactive setup flags with explicit root page ids |
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: "ktx ingest"
|
||||
description: "Build or refresh KTX context, or capture text into KTX memory."
|
||||
description: "Build or refresh ktx context, or capture text into ktx memory."
|
||||
---
|
||||
|
||||
`ktx ingest` builds or refreshes KTX context from configured connections, and
|
||||
can also capture free-form text into KTX memory. Database connections build
|
||||
`ktx ingest` builds or refreshes **ktx** context from configured connections, and
|
||||
can also capture free-form text into **ktx** memory. Database connections build
|
||||
schema context. Context-source connections ingest metadata from tools such as
|
||||
dbt, Looker, Metabase, MetricFlow, LookML, and Notion. Pass `--text` or
|
||||
`--file` to capture inline text or text files into memory instead.
|
||||
|
|
@ -18,7 +18,7 @@ ktx ingest [options] [connectionId]
|
|||
- Bare `ktx ingest` (no positional, no `--all`) ingests every configured
|
||||
connection.
|
||||
- `ktx ingest <connectionId>` ingests one configured connection.
|
||||
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into KTX
|
||||
- `ktx ingest --text "..."` (or `--file <path>`) captures notes into **ktx**
|
||||
memory instead of ingesting a connection.
|
||||
|
||||
Database connections run before context-source connections when more than one
|
||||
|
|
@ -29,14 +29,14 @@ connection is selected.
|
|||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--all` | Ingest all configured connections (same as bare invocation) | `false` |
|
||||
| `--fast` | Use deterministic database schema ingest | Stored connection default, or `fast` |
|
||||
| `--deep` | Use AI-enriched database ingest | Stored connection default, or `fast` |
|
||||
| `--fast` | Use deterministic fast database ingest | Stored connection default, or `fast` |
|
||||
| `--deep` | Use deep database ingest with AI-generated descriptions, embeddings, and relationship evidence | Stored connection default, or `fast` |
|
||||
| `--query-history` | Include database query-history usage patterns | Stored connection default |
|
||||
| `--no-query-history` | Skip database query-history usage patterns for this run | Stored connection default |
|
||||
| `--query-history-window-days <days>` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default |
|
||||
| `--text <content>` | Capture inline text into KTX memory; repeatable | `[]` |
|
||||
| `--file <path>` | Capture a text file into KTX memory; use `-` for stdin; repeatable | `[]` |
|
||||
| `--connection-id <connectionId>` | KTX connection id to tag captured text/file notes | - |
|
||||
| `--text <content>` | Capture inline text into **ktx** memory; repeatable | `[]` |
|
||||
| `--file <path>` | Capture a text file into **ktx** memory; use `-` for stdin; repeatable | `[]` |
|
||||
| `--connection-id <connectionId>` | **ktx** connection id to tag captured text/file notes | - |
|
||||
| `--user-id <id>` | Memory user id for text/file capture attribution | `local-cli` |
|
||||
| `--fail-fast` | Stop after the first failed text/file item | `false` |
|
||||
| `--plain` | Print plain text output | `true` |
|
||||
|
|
@ -48,14 +48,14 @@ connection is selected.
|
|||
database connections. Query-history flags apply only to database connections
|
||||
that support query history. The window flag applies to BigQuery and Snowflake;
|
||||
Postgres reads the current `pg_stat_statements` aggregate data instead of a
|
||||
time-windowed history table. Query-history ingest runs after schema ingest and
|
||||
time-windowed history table. Query-history ingest runs after fast ingest and
|
||||
requires deep ingest readiness.
|
||||
|
||||
When more than one connection is selected, database ingest runs first, then
|
||||
source ingest and memory updates run for source connections.
|
||||
context-source ingest and memory updates run for context-source connections.
|
||||
|
||||
Some ingest paths use the managed KTX Python runtime. Query-history ingest uses
|
||||
it for SQL analysis, and Looker source ingest uses it for Looker identifier
|
||||
Some ingest paths use the managed **ktx** Python runtime. Query-history ingest uses
|
||||
it for SQL analysis, and Looker context-source ingest uses it for Looker identifier
|
||||
parsing. In an interactive terminal, `ktx ingest` prompts before installing the
|
||||
required runtime features. Use `--yes` to install them without prompting, or
|
||||
use `--no-input` to fail fast with install guidance.
|
||||
|
|
@ -69,13 +69,13 @@ use `--no-input` to fail fast with install guidance.
|
|||
# Build every configured connection (bare = --all)
|
||||
ktx ingest
|
||||
|
||||
# Build one database or source connection
|
||||
# Build one database or context-source connection
|
||||
ktx ingest warehouse
|
||||
|
||||
# Force deterministic database schema ingest
|
||||
# Force deterministic fast database ingest
|
||||
ktx ingest warehouse --fast
|
||||
|
||||
# Force AI-enriched database ingest
|
||||
# Force deep database ingest with AI enrichment
|
||||
ktx ingest warehouse --deep
|
||||
|
||||
# Include query-history usage patterns
|
||||
|
|
@ -83,7 +83,7 @@ ktx ingest warehouse --deep --query-history
|
|||
# Set the lookback window for BigQuery or Snowflake query history
|
||||
ktx ingest warehouse --query-history-window-days 30
|
||||
|
||||
# Build a source connection
|
||||
# Build a context-source connection
|
||||
ktx ingest notion
|
||||
|
||||
# Capture inline text into memory
|
||||
|
|
@ -114,11 +114,11 @@ notion skipped skipped done done
|
|||
Use `--json` when a script or agent needs the selected plan and per-target
|
||||
results.
|
||||
|
||||
## Inspect source ingest traces
|
||||
## Inspect context-source ingest traces
|
||||
|
||||
Source ingest writes persistent JSONL traces for postmortem debugging. Plain
|
||||
ingest output prints the trace path near the report, run, and job identifiers
|
||||
when a trace is available:
|
||||
Context-source ingest writes persistent JSONL traces for postmortem debugging.
|
||||
Plain ingest output prints the trace path near the report, run, and job
|
||||
identifiers when a trace is available:
|
||||
|
||||
```text
|
||||
Report: report-abc123
|
||||
|
|
@ -141,7 +141,7 @@ jq -c '. | {at, level, phase, event, durationMs, data, error}' \
|
|||
.ktx/ingest-traces/<jobId>/trace.jsonl
|
||||
```
|
||||
|
||||
KTX writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
|
||||
**ktx** writes `debug` trace events by default. Set `KTX_INGEST_TRACE_LEVEL` to
|
||||
`error`, `info`, `debug`, or `trace` before running ingest to change the trace
|
||||
verbosity:
|
||||
|
||||
|
|
@ -155,7 +155,7 @@ KTX_INGEST_TRACE_LEVEL=trace ktx ingest metabase
|
|||
|-------|-------|----------|
|
||||
| Connection not configured | The connection id is not present in `ktx.yaml` | Add the connection with `ktx setup` or update `ktx.yaml` |
|
||||
| Deep readiness is missing | `--deep` or query history needs model, embedding, and scan-enrichment configuration | Run `ktx setup` or rerun with `--fast` |
|
||||
| Query history is unsupported | The selected database driver does not support query history | Run schema ingest without query-history flags |
|
||||
| Query history is unsupported | The selected database driver does not support query history | Run fast ingest without query-history flags |
|
||||
| Python runtime is missing | The selected ingest target needs runtime-backed SQL analysis or source parsing | Accept the interactive prompt, rerun with `--yes`, or run the suggested `ktx admin runtime install` command |
|
||||
| Source options were ignored | Depth and query-history flags were supplied for a non-database source | Omit database-only flags when ingesting source connections |
|
||||
| Context-source options were ignored | Depth and query-history flags were supplied for a context-source connection | Omit database-only flags when ingesting context-source connections |
|
||||
| Text ingest stops early | `--fail-fast` was used and one item failed | Fix the failed item or rerun without `--fail-fast` to collect all failures |
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
title: "ktx mcp"
|
||||
description: "Run the KTX MCP HTTP server for agent clients."
|
||||
description: "Run the ktx MCP HTTP server for agent clients."
|
||||
---
|
||||
|
||||
`ktx mcp` starts, stops, inspects, and tails the local KTX MCP server for a KTX
|
||||
`ktx mcp` starts, stops, inspects, and tails the local **ktx** MCP server for a **ktx**
|
||||
project. Use it when an agent client connects through MCP instead of generated
|
||||
CLI instructions.
|
||||
|
||||
|
|
@ -17,8 +17,8 @@ ktx mcp <subcommand> [options]
|
|||
|
||||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `start` | Start the KTX MCP HTTP server |
|
||||
| `stop` | Stop the KTX MCP daemon |
|
||||
| `start` | Start the **ktx** MCP HTTP server |
|
||||
| `stop` | Stop the **ktx** MCP daemon |
|
||||
| `status` | Show daemon status, URL, PID, token mode, and project path |
|
||||
| `logs` | Print the daemon log |
|
||||
|
||||
|
|
@ -65,6 +65,6 @@ hosts and origins for browser clients.
|
|||
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or pass `--project-dir <path>` |
|
||||
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a **ktx** project or pass `--project-dir <path>` |
|
||||
| Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--token <token>` or set `KTX_MCP_TOKEN` |
|
||||
| Client cannot connect | Host, port, token, allowed host, or allowed origin does not match the client | Check `ktx mcp status`, then restart with explicit `--host`, `--port`, `--allowed-host`, and `--allowed-origin` values |
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
title: "ktx setup"
|
||||
description: "Set up or resume a local KTX project."
|
||||
description: "Set up or resume a local ktx project."
|
||||
---
|
||||
|
||||
`ktx setup` is the guided configuration flow for a local KTX project. It can
|
||||
`ktx setup` is the guided configuration flow for a local **ktx** project. It can
|
||||
create or resume `ktx.yaml`, configure LLM and embedding providers, add
|
||||
database and context-source connections, prepare required runtime features,
|
||||
build initial context, and install agent integrations.
|
||||
|
||||
When you run bare `ktx` in an interactive terminal outside any KTX project, the
|
||||
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
|
||||
CLI starts this same setup flow. Inside an existing project, `ktx setup`
|
||||
resumes from incomplete setup state or opens the setup menu.
|
||||
|
||||
|
|
@ -52,7 +52,7 @@ prompts.
|
|||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--llm-backend <backend>` | LLM backend: `anthropic`, `vertex`, or `claude-code` |
|
||||
| `--llm-backend claude-code` | Use the local Claude Code session for KTX LLM calls |
|
||||
| `--llm-backend claude-code` | Use the local Claude Code session for **ktx** LLM calls |
|
||||
| `--llm-model <model>` | LLM model ID or backend model alias to validate and save |
|
||||
| `--anthropic-api-key-env <name>` | Environment variable containing the Anthropic API key |
|
||||
| `--anthropic-api-key-file <path>` | File containing the Anthropic API key |
|
||||
|
|
@ -75,18 +75,18 @@ of Anthropic API key or Vertex flags. For Claude Code, `--llm-model` accepts
|
|||
| `--embedding-api-key-file <path>` | File containing the embedding provider API key |
|
||||
| `--skip-embeddings` | Leave embedding setup incomplete |
|
||||
|
||||
`sentence-transformers` uses the KTX-managed Python runtime. Choose only one
|
||||
`sentence-transformers` uses the **ktx**-managed Python runtime. Choose only one
|
||||
embedding credential source.
|
||||
|
||||
### Runtime
|
||||
|
||||
Setup prepares the managed Python runtime when your selected configuration
|
||||
needs it. In the full setup flow, the runtime step runs after database and
|
||||
source setup and before the initial context build.
|
||||
context-source setup and before the initial context build.
|
||||
|
||||
KTX prepares the `core` runtime feature when query-history ingest, Looker
|
||||
source ingest, database introspection fallback, or daemon-backed context build
|
||||
paths need it. KTX prepares the `local-embeddings` runtime feature when you
|
||||
**ktx** prepares the `core` runtime feature when query-history ingest, Looker
|
||||
context-source ingest, database introspection fallback, or daemon-backed
|
||||
context build paths need it. **ktx** prepares the `local-embeddings` runtime feature when you
|
||||
choose managed local `sentence-transformers` embeddings. Existing external
|
||||
daemon URLs, such as `KTX_DAEMON_URL` or `KTX_SQL_ANALYSIS_URL`, satisfy the
|
||||
matching dependency and skip managed runtime installation for that dependency.
|
||||
|
|
@ -109,7 +109,7 @@ runtime features are missing.
|
|||
| `--database-schema <schema>` | Database schema or dataset to include; repeatable |
|
||||
| `--skip-databases` | Leave database setup incomplete |
|
||||
|
||||
KTX needs at least one database connection before it can build database
|
||||
**ktx** needs at least one database connection before it can build database
|
||||
context. Use `--skip-databases` only when intentionally leaving the project
|
||||
incomplete.
|
||||
|
||||
|
|
@ -134,25 +134,25 @@ Enabling query history makes deep ingest readiness matter for later
|
|||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--source <type>` | Source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
|
||||
| `--source-connection-id <id>` | Connection id for source setup |
|
||||
| `--source <type>` | Context-source connector type: `dbt`, `metricflow`, `metabase`, `looker`, `lookml`, or `notion` |
|
||||
| `--source-connection-id <id>` | Connection id for context-source setup |
|
||||
| `--source-path <path>` | Local source path for dbt, MetricFlow, or LookML |
|
||||
| `--source-git-url <url>` | Git URL for dbt, MetricFlow, or LookML |
|
||||
| `--source-branch <branch>` | Git branch for source setup |
|
||||
| `--source-subpath <path>` | Repo subpath for source setup |
|
||||
| `--source-branch <branch>` | Git branch for context-source setup |
|
||||
| `--source-subpath <path>` | Repo subpath for context-source setup |
|
||||
| `--source-auth-token-ref <ref>` | `env:` or `file:` credential reference for source repo auth |
|
||||
| `--source-url <url>` | Source service URL for Metabase or Looker |
|
||||
| `--source-api-key-ref <ref>` | `env:` or `file:` API key reference for Metabase or Notion |
|
||||
| `--source-client-id <id>` | Looker client id |
|
||||
| `--source-client-secret-ref <ref>` | `env:` or `file:` Looker client secret reference |
|
||||
| `--source-warehouse-connection-id <id>` | Warehouse connection id used for source mapping |
|
||||
| `--source-warehouse-connection-id <id>` | Warehouse connection id used for context-source mapping |
|
||||
| `--source-project-name <name>` | dbt project name override |
|
||||
| `--source-profiles-path <path>` | dbt profiles path |
|
||||
| `--source-target <target>` | dbt target or source-specific mapping target |
|
||||
| `--source-target <target>` | dbt target or context-source-specific mapping target |
|
||||
| `--metabase-database-id <id>` | Metabase database id to map |
|
||||
| `--notion-crawl-mode <mode>` | Notion crawl mode: `all_accessible` or `selected_roots` |
|
||||
| `--notion-root-page-id <id>` | Notion root page id; repeatable |
|
||||
| `--skip-sources` | Mark optional source setup complete with no sources |
|
||||
| `--skip-sources` | Mark optional context-source setup complete with no sources |
|
||||
|
||||
Choose only one source location: `--source-path` or `--source-git-url`.
|
||||
|
||||
|
|
@ -165,7 +165,7 @@ ktx setup
|
|||
# Run setup for a specific project directory
|
||||
ktx setup --project-dir ./analytics
|
||||
|
||||
# Use Claude Code with Opus for KTX LLM calls
|
||||
# Use Claude Code with Opus for ktx LLM calls
|
||||
ktx setup \
|
||||
--project-dir ./analytics \
|
||||
--llm-backend claude-code \
|
||||
|
|
@ -211,14 +211,14 @@ Interactive setup renders prompts and progress messages. Use `ktx status` to
|
|||
check setup and context readiness after setup exits.
|
||||
|
||||
```text
|
||||
KTX project: /home/user/analytics
|
||||
ktx project: /home/user/analytics
|
||||
Project ready: yes
|
||||
LLM ready: yes (claude-sonnet-4-6)
|
||||
Embeddings ready: yes (text-embedding-3-small)
|
||||
Databases configured: yes (postgres-warehouse)
|
||||
Context sources configured: yes (dbt-main)
|
||||
Runtime ready: yes (core)
|
||||
KTX context built: yes
|
||||
ktx context built: yes
|
||||
Agent integration ready: yes (codex:project)
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "ktx sl"
|
||||
description: "List, search, validate, or query semantic-layer sources."
|
||||
description: "List, search, validate, or query semantic sources."
|
||||
---
|
||||
|
||||
Interact with your project's semantic layer. Semantic sources are YAML
|
||||
|
|
@ -15,8 +15,8 @@ ktx sl validate <sourceName> [options]
|
|||
ktx sl query [options]
|
||||
```
|
||||
|
||||
- Bare `ktx sl` lists semantic-layer sources.
|
||||
- `ktx sl <query...>` searches semantic-layer sources (multi-word queries are
|
||||
- Bare `ktx sl` lists semantic sources.
|
||||
- `ktx sl <query...>` searches semantic sources (multi-word queries are
|
||||
joined with a space).
|
||||
- `ktx sl validate` and `ktx sl query` remain as explicit subcommands.
|
||||
|
||||
|
|
@ -24,10 +24,10 @@ ktx sl query [options]
|
|||
|
||||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| (none, no query) | List semantic-layer sources |
|
||||
| (none, with query) | Search semantic-layer sources |
|
||||
| `validate <sourceName>` | Validate a semantic-layer source against the database schema |
|
||||
| `query` | Compile or execute a Semantic Query |
|
||||
| (none, no query) | List semantic sources |
|
||||
| (none, with query) | Search semantic sources |
|
||||
| `validate <sourceName>` | Validate a semantic source against the database schema |
|
||||
| `query` | Compile or execute a semantic query |
|
||||
|
||||
## Options
|
||||
|
||||
|
|
@ -35,7 +35,7 @@ ktx sl query [options]
|
|||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--connection-id <id>` | Filter by KTX connection id | - |
|
||||
| `--connection-id <id>` | Filter by **ktx** connection id | - |
|
||||
| `--limit <number>` | Maximum search results (search mode only) | - |
|
||||
| `--output <mode>` | Output mode: `pretty` (default in TTY), `plain` (TSV), or `json` | `pretty` |
|
||||
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
|
||||
|
|
@ -44,14 +44,14 @@ ktx sl query [options]
|
|||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--connection-id <id>` | KTX connection id (required) | - |
|
||||
| `--connection-id <id>` | **ktx** connection id (required) | - |
|
||||
|
||||
### `sl query`
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--connection-id <id>` | KTX connection id | - |
|
||||
| `--query-file <path>` | JSON Semantic Query file | - |
|
||||
| `--connection-id <id>` | **ktx** connection id | - |
|
||||
| `--query-file <path>` | JSON semantic query file | - |
|
||||
| `--measure <measure>` | Measure to query; repeatable (at least one required) | - |
|
||||
| `--dimension <dimension>` | Dimension to include; repeatable | - |
|
||||
| `--filter <filter>` | Filter expression; repeatable | - |
|
||||
|
|
@ -66,7 +66,7 @@ ktx sl query [options]
|
|||
| `--max-rows <n>` | Maximum rows to return when executing | - |
|
||||
|
||||
`sl query` requires at least one `--measure` unless `--query-file` is set.
|
||||
`--query-file` should point to a JSON Semantic Query object.
|
||||
`--query-file` should point to a JSON semantic query object.
|
||||
|
||||
## Examples
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: "ktx sql"
|
|||
description: "Execute parser-validated read-only SQL against a configured connection."
|
||||
---
|
||||
|
||||
Run read-only SQL against a database connection in your KTX project. The command
|
||||
Run read-only SQL against a database connection in your **ktx** project. The command
|
||||
validates the statement before execution and only accepts a single `SELECT` or
|
||||
`WITH` query.
|
||||
|
||||
|
|
@ -22,7 +22,7 @@ JSON.
|
|||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `-c`, `--connection <id>` | KTX database connection id. Required. | - |
|
||||
| `-c`, `--connection <id>` | **ktx** database connection id. Required. | - |
|
||||
| `--max-rows <n>` | Maximum rows to return. Must be between `1` and `10000`. | `1000` |
|
||||
| `--output <mode>` | Output mode: `pretty`, `plain` (TSV), or `json`. | `pretty` |
|
||||
| `--json` | Shortcut for `--output=json` (overrides `--output`). | `false` |
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
title: "ktx status"
|
||||
description: "Check KTX setup and project readiness."
|
||||
description: "Check ktx setup and project readiness."
|
||||
---
|
||||
|
||||
Run the KTX readiness doctor. Inside a KTX project, this checks setup,
|
||||
Run the **ktx** readiness doctor. Inside a **ktx** project, this checks setup,
|
||||
project configuration, semantic search, query history, connections, and related
|
||||
diagnostics. Outside a project, it checks local CLI setup readiness so you know
|
||||
whether `ktx setup` can run.
|
||||
|
|
@ -53,7 +53,7 @@ flow, then rerun `ktx status`.
|
|||
|
||||
```json
|
||||
{
|
||||
"title": "KTX project doctor",
|
||||
"title": "ktx project doctor",
|
||||
"checks": [
|
||||
{
|
||||
"id": "project-config",
|
||||
|
|
@ -69,7 +69,7 @@ flow, then rerun `ktx status`.
|
|||
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a KTX project or set `KTX_PROJECT_DIR` for project checks |
|
||||
| No **ktx** project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | `ktx status` runs setup checks; run from a **ktx** project or set `KTX_PROJECT_DIR` for project checks |
|
||||
| Project config check fails | The project directory is missing or has an invalid `ktx.yaml` | Run `ktx setup` to resume setup |
|
||||
| Schema validation fails | `ktx.yaml` does not match the current config schema | Run `ktx status --validate --json` for structured issue details, then edit `ktx.yaml` or rerun `ktx setup` |
|
||||
| Semantic search check warns | Embeddings are not configured or the provider probe failed | Run `ktx setup` or inspect the check's `fix` field in JSON output |
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ title: "ktx wiki"
|
|||
description: "List or search wiki pages."
|
||||
---
|
||||
|
||||
List and search wiki pages in your KTX project. Wiki pages are Markdown
|
||||
List and search wiki pages in your **ktx** project. Wiki pages are Markdown
|
||||
documents that capture business definitions, rules, and gotchas. Agents search
|
||||
them for context when answering questions about your data.
|
||||
|
||||
|
|
@ -30,9 +30,9 @@ Edit the Markdown files under `wiki/` directly, or ingest source content with
|
|||
| `--json` | Shortcut for `--output=json` (overrides `--output`) | `false` |
|
||||
|
||||
`ktx wiki <query>` uses hybrid search when `storage.search` is `sqlite-fts5`.
|
||||
KTX combines lexical SQLite FTS5 matches, token matches, and semantic matches
|
||||
**ktx** combines lexical SQLite FTS5 matches, token matches, and semantic matches
|
||||
from wiki page embeddings stored in `.ktx/db.sqlite`. If embeddings are not
|
||||
configured or the embedding backend is unavailable, KTX skips the semantic lane
|
||||
configured or the embedding backend is unavailable, **ktx** skips the semantic lane
|
||||
and keeps lexical and token results.
|
||||
|
||||
## Examples
|
||||
|
|
@ -105,7 +105,7 @@ score rather than a percentage.
|
|||
}
|
||||
```
|
||||
|
||||
When you pass the global `--debug` flag, KTX writes search diagnostics to
|
||||
When you pass the global `--debug` flag, **ktx** writes search diagnostics to
|
||||
stderr and leaves stdout unchanged. This is useful with `--json` because stdout
|
||||
stays machine-readable:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: "ktx"
|
||||
description: "Root command map, global options, and project resolution for the KTX CLI."
|
||||
description: "Root command map, global options, and project resolution for the ktx CLI."
|
||||
---
|
||||
|
||||
The `ktx` CLI sets up local projects, builds agent-ready context, checks
|
||||
connections, queries semantic-layer sources, searches wiki pages, runs the MCP
|
||||
connections, queries semantic sources, searches wiki pages, runs the MCP
|
||||
server, and manages the bundled Python runtime.
|
||||
|
||||
## Command signature
|
||||
|
|
@ -13,7 +13,7 @@ server, and manages the bundled Python runtime.
|
|||
ktx [global-options] <command>
|
||||
```
|
||||
|
||||
When you run bare `ktx` in an interactive terminal outside any KTX project, the
|
||||
When you run bare `ktx` in an interactive terminal outside any **ktx** project, the
|
||||
CLI starts the same guided setup flow as `ktx setup`. Inside an existing
|
||||
project, use command-specific help:
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or
|
|||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--project-dir <path>` | KTX project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
|
||||
| `--project-dir <path>` | **ktx** project directory. Defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`, then the current working directory. |
|
||||
| `--debug` | Print diagnostic dispatch and project-resolution details to stderr. |
|
||||
| `-v`, `--version` | Show the CLI package name and version. |
|
||||
| `-h`, `--help` | Show help for the current command. |
|
||||
|
|
@ -74,7 +74,7 @@ The public context-build entrypoint is `ktx ingest [connectionId]` or
|
|||
## Project resolution
|
||||
|
||||
Most commands are project-aware. Pass `--project-dir <path>` when scripting or
|
||||
when you are outside the project directory. If you omit it, KTX checks
|
||||
when you are outside the project directory. If you omit it, **ktx** checks
|
||||
`KTX_PROJECT_DIR`, then walks upward for the nearest `ktx.yaml`, then falls back
|
||||
to the current directory.
|
||||
|
||||
|
|
@ -93,7 +93,7 @@ ktx ingest warehouse
|
|||
# Build every configured connection
|
||||
ktx ingest
|
||||
|
||||
# Search semantic-layer sources and wiki pages
|
||||
# Search semantic sources and wiki pages
|
||||
ktx sl "revenue"
|
||||
ktx wiki "revenue recognition"
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue