mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
e7538fb807
Fast mode (the ktx ingest --fast/--deep database-ingest depth toggle) is removed.
ktx ingest now always builds the full enriched ("deep") context. There is no
structural fallback: a database connection without a configured model and
embeddings fails the enrichment-readiness preflight before any work runs, with
a 'Run ktx setup to configure a model and embeddings' hint.
- Remove --fast/--deep flags, the per-connection context.depth field, and the
ktx setup depth prompt (delete setup-database-context-depth.ts).
- Rename ingest-depth.ts -> connection-drivers.ts; ingest always requests scan
mode 'enriched'; readiness gate (enrichmentReadinessGaps) runs for every
database target.
- Drop the database-context-depth telemetry step (Node + Python schema mirrors
regenerated).
- Update CLI, setup, context-build view, docs, the public ktx skill, and the
release-smoke / artifacts scripts (now assert the no-LLM guard failure).
ktx status --fast (a separate network-probe flag) is unchanged.
Follow-ups: KLO-726 (live progress for ktx ingest --all), KLO-727 (restore
credentialed successful-ingest release smoke coverage).
161 lines
4.5 KiB
Text
161 lines
4.5 KiB
Text
---
|
|
title: Serving Agents
|
|
description: Expose ktx context to Claude Code, Codex, Cursor, OpenCode, and custom agents.
|
|
---
|
|
|
|
**ktx** serves agents through the CLI and project-local instruction files. Agents
|
|
read generated rules, call **ktx** commands, inspect context files, and use JSON for
|
|
structured results.
|
|
|
|
## Recommended setup
|
|
|
|
Run the agent install step from a ktx project:
|
|
|
|
```bash
|
|
ktx setup --agents
|
|
```
|
|
|
|
Or install a specific target:
|
|
|
|
```bash
|
|
ktx setup --agents --target codex
|
|
```
|
|
|
|
Supported targets:
|
|
|
|
| Target | Generated project file |
|
|
|--------|------------------------|
|
|
| Claude Code | `.claude/skills/ktx/SKILL.md` |
|
|
| Codex | `.agents/skills/ktx/SKILL.md` |
|
|
| Cursor | `.cursor/rules/ktx.mdc` |
|
|
| OpenCode | `.opencode/commands/ktx.md` |
|
|
| Universal `.agents` | `.agents/skills/ktx/SKILL.md` |
|
|
|
|
Claude Code and Codex also support global installs:
|
|
|
|
```bash
|
|
ktx setup --agents --target claude-code --global
|
|
ktx setup --agents --target codex --global
|
|
```
|
|
|
|
Installed files are recorded in `.ktx/agents/install-manifest.json`. Rerun
|
|
`ktx setup --agents` after moving a checkout or reinstalling the CLI.
|
|
|
|
## Agent command set
|
|
|
|
All supported clients use the same command surface. Use `--project-dir` outside
|
|
the **ktx** project directory.
|
|
|
|
### Readiness
|
|
|
|
```bash
|
|
ktx status --json
|
|
```
|
|
|
|
Run this before relying on context. It reports project, provider, connection,
|
|
context-build, and agent-integration readiness.
|
|
|
|
### Semantic layer discovery
|
|
|
|
```bash
|
|
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,
|
|
and files to inspect.
|
|
|
|
### Semantic-layer validation and queries
|
|
|
|
```bash
|
|
ktx sl validate orders --connection-id warehouse
|
|
```
|
|
|
|
Compile SQL before executing:
|
|
|
|
```bash
|
|
ktx sl query \
|
|
--connection-id warehouse \
|
|
--measure orders.total_revenue \
|
|
--dimension orders.created_date \
|
|
--format sql
|
|
```
|
|
|
|
Execute only when the task calls for live data:
|
|
|
|
```bash
|
|
ktx sl query \
|
|
--connection-id warehouse \
|
|
--measure orders.total_revenue \
|
|
--dimension orders.status \
|
|
--execute \
|
|
--max-rows 100
|
|
```
|
|
|
|
For complex calls, agents can write a JSON query object and pass it with
|
|
`--query-file`.
|
|
|
|
### Wiki context
|
|
|
|
```bash
|
|
ktx wiki --json
|
|
ktx wiki "revenue recognition" --json --limit 10
|
|
```
|
|
|
|
Search the wiki for business definitions, metric caveats, process rules, and
|
|
non-obvious terms.
|
|
|
|
### Context refresh
|
|
|
|
Agents can refresh context when the user asks them to:
|
|
|
|
```bash
|
|
ktx ingest warehouse
|
|
ktx ingest
|
|
ktx ingest --file docs/revenue-notes.md --connection-id warehouse
|
|
```
|
|
|
|
Database ingest builds enriched context and requires a configured model and
|
|
embeddings; run `ktx setup` first if they are not ready.
|
|
|
|
## Good agent behavior
|
|
|
|
Agents should:
|
|
|
|
- Run `ktx status --json` before using **ktx** context.
|
|
- 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.
|
|
- Validate edited semantic sources with `ktx sl validate`.
|
|
- Keep generated context changes reviewable in git.
|
|
|
|
**ktx** is a local context layer with a CLI and plain project files. Do not assume a
|
|
background server, ORPC route, frontend app, or external migration system.
|
|
|
|
## Manual setup
|
|
|
|
Use manual setup for custom agents that can read project-local instructions.
|
|
|
|
1. Install the universal target:
|
|
|
|
```bash
|
|
ktx setup --agents --target universal
|
|
```
|
|
|
|
2. Configure the agent to read `.agents/skills/ktx/SKILL.md`.
|
|
3. Open the agent in the **ktx** project directory.
|
|
4. Ask it to run `ktx status --json` and summarize readiness.
|
|
|
|
For per-client notes, see [Agent Clients](/docs/integrations/agent-clients).
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Likely cause | Recovery |
|
|
|---------|--------------|----------|
|
|
| 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 <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 |
|