Skip to content

kweaver-ai/kweaver-sdk

BranchesTags

Repository files navigation

KWeaver SDK

Skill CI License: MIT

Part of the KWeaver ecosystem — an open-source platform for building, managing, and querying knowledge networks.

Give AI agents (Claude Code, GPT, custom agents, etc.) access to KWeaver knowledge networks and Decision Agents via the kweaver CLI. Also provides Python and TypeScript SDKs for programmatic integration.

中文文档

Installation

TypeScript CLI (recommended — includes interactive agent chat TUI)

npm install -g @kweaver-ai/kweaver-sdk

Requires Node.js 22+. After installation, use the kweaver command.

TypeScript SDK (programmatic)

npm install @kweaver-ai/kweaver-sdk
import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";

// Zero-config: reads credentials saved by `kweaver auth login`
const client = new KWeaverClient();

// Or pass credentials explicitly
const client = new KWeaverClient({
  baseUrl: "https://your-kweaver.com",
  accessToken: "your-token",
});

const kns   = await client.knowledgeNetworks.list();
const reply = await client.agents.chat("agent-id", "Hello");
console.log(reply.text);

Python CLI (alternative — for testing or Node-free environments)

pip install kweaver-sdk[cli]

Requires Python >= 3.10. After installation, use the same kweaver command.

Python SDK (programmatic)

pip install kweaver-sdk
import kweaver

kweaver.configure(config=True, bkn_id="your-bkn-id", agent_id="your-agent-id")

results = kweaver.search("What risks exist in the supply chain?")
reply   = kweaver.chat("Summarise the top 3 risks")
print(reply.content)

Overview

Entry point Install Purpose
TS CLI npm install -g @kweaver-ai/kweaver-sdk Primary CLI with Ink TUI and streaming agent chat
TS SDK npm install @kweaver-ai/kweaver-sdk Programmatic API — import { KWeaverClient } from "@kweaver-ai/kweaver-sdk"
Python CLI pip install kweaver-sdk[cli] Alternative CLI, feature-parity with TS CLI
Python SDK pip install kweaver-sdk Programmatic API — from kweaver import KWeaverClient

Both CLIs share the same command structure (kweaver auth, kweaver bkn, kweaver agent, kweaver skill, kweaver context-loader, …) and credentials stored in ~/.kweaver/.

Authentication

kweaver auth login https://your-kweaver-instance.com
kweaver auth login https://your-kweaver-instance.com --alias prod

Or use environment variables: KWEAVER_BASE_URL, KWEAVER_BUSINESS_DOMAIN, KWEAVER_TOKEN, or the CLI flags kweaver --base-url <url> --token <access-token> … (stateless mode; see TypeScript README). With saved ~/.kweaver/ sessions from OAuth2 browser login, the default is to exchange refresh_token for a new access token when the access token expires (no extra flags). For TLS in the Node kweaver CLI, see KWEAVER_TLS_INSECURE and NODE_TLS_REJECT_UNAUTHORIZED in the TypeScript README.

Headless hosts (SSH, CI, containers — no browser)

The npm kweaver CLI supports logging in on a machine that cannot open a browser:

  1. On any machine with a browser, run kweaver auth login https://your-instance. After success, the local callback page shows a one-line command you can copy (or run kweaver auth export / kweaver auth export --json).
  2. On the headless machine, run that command — it uses --client-id, --client-secret, and --refresh-token to exchange for tokens and save ~/.kweaver/ as usual.

Details: packages/typescript/README.md (section Headless / Server Authentication). The Python kweaver CLI still uses interactive browser login; you can reuse the same ~/.kweaver/ directory copied from a machine where the Node CLI completed login.

Platform configuration (business domain)

Most API calls send x-business-domain. Set or verify this right after login — wrong or default-only bd_public often explains empty lists on DIP-style deployments.

kweaver config show              # current platform + resolved business domain
kweaver config list-bd         # list domains from the platform (needs login)
kweaver config set-bd <uuid>   # persist default for this platform

Priority: KWEAVER_BUSINESS_DOMAIN env → per-platform ~/.kweaver/.../config.json → bd_public. After a successful kweaver auth login, the CLI tries to auto-pick a domain (prefer bd_public in the list, else the first entry) when nothing is configured yet.

See skills/kweaver-core/references/config.md.

TypeScript SDK Usage

Simple API (recommended)

import kweaver from "@kweaver-ai/kweaver-sdk/kweaver";

// Uses saved credentials from `kweaver auth login`
kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });

// Search the BKN
const results = await kweaver.search("What risks exist in the supply chain?");
for (const concept of results.concepts) console.log(concept.concept_name);

// Chat with an agent
const reply = await kweaver.chat("Summarise the top 3 risks");
console.log(reply.text);

// After adding datasources or modifying object types, rebuild the BKN index
await kweaver.weaver({ wait: true });

// List available BKNs and agents
const bknList   = await kweaver.bkns();
const agentList = await kweaver.agents();

Full client API (advanced)

import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";

const client = new KWeaverClient();   // reads ~/.kweaver/ credentials

// Knowledge networks
const kns = await client.knowledgeNetworks.list({ limit: 10 });
const ots = await client.knowledgeNetworks.listObjectTypes("bkn-id");
const rts = await client.knowledgeNetworks.listRelationTypes("bkn-id");

// Agent chat (single-shot)
const reply = await client.agents.chat("agent-id", "Hello");
console.log(reply.text, reply.conversationId);

// Agent chat (streaming)
await client.agents.stream("agent-id", "Hello", {
  onTextDelta: (chunk) => process.stdout.write(chunk),
});

// BKN engine — instance queries, subgraph, action execution
const instances = await client.bkn.queryInstances("bkn-id", "ot-id", { limit: 20 });
const graph     = await client.bkn.querySubgraph("bkn-id", { /* path spec */ });
await client.bkn.executeAction("bkn-id", "at-id", { /* params */ });
const logs      = await client.bkn.listActionLogs("bkn-id");

// Data sources & vega-backend resources
const dsList = await client.datasources.list();
const tables = await client.datasources.listTables("ds-id");
const resId  = await client.resources.create({ name: "v", datasourceId: "ds-id", table: "orders" });

// Dataflow automation (CSV import pipeline, etc.)
const result = await client.dataflows.execute({
  title: "import", trigger_config: { operator: "manual" },
  steps: [{ id: "s1", title: "load", operator: "csv_import", parameters: {} }],
});

// Vega observability
const catalogs = await client.vega.listCatalogs();

// Context Loader (semantic search over a knowledge network)
const cl      = client.contextLoader(mcpUrl, "bkn-id");
const results = await cl.search({ query: "hypertension treatment" });

Python SDK Usage

Pure Python authentication

You can sign in from Python alone; tokens land in ~/.kweaver/ just like the CLIs:

  • HTTP sign-in (RSA-encrypted password, aligned with kweaver auth login --http-signin): kweaver.login("https://…", username="…", password="…"). Use new_password= when the server requires an initial password change (401001017).
  • Refresh token: kweaver.login("https://…", refresh_token="…", client_id="…", client_secret="…").
  • No-auth hosts: kweaver.login("https://…", no_auth=True).
  • Browser OAuth: kweaver.login("https://…") opens a browser; open_browser=False matches the headless paste flow.

Helpers such as http_signin, whoami, and list_platforms live in kweaver.auth. For lazy sign-in on first API call, use kweaver.configure(..., username=…, password=…) or HttpSigninAuth.

Simple API (recommended)

import kweaver

# Uses saved credentials from `kweaver auth login`
kweaver.configure(config=True, bkn_id="your-bkn-id", agent_id="your-agent-id")

# Search the BKN
results = kweaver.search("What risks exist in the supply chain?")
for concept in results.concepts:
    print(concept.concept_name)

# Chat with an agent
reply = kweaver.chat("Summarise the top 3 risks")
print(reply.content)

# After adding datasources or modifying object types, rebuild the BKN index
kweaver.weaver(wait=True)

# List available BKNs and agents
for bkn in kweaver.bkns():
    print(bkn.id, bkn.name)

Full client API (advanced)

from kweaver import KWeaverClient, ConfigAuth

client = KWeaverClient(auth=ConfigAuth())   # reads ~/.kweaver/ credentials

# BKNs
bkns = client.knowledge_networks.list()
ots  = client.object_types.list("bkn-id")

# Agent chat
msg = client.conversations.send_message("", "Hello", agent_id="agent-id")
print(msg.content)

# Model factory (mf-model-manager + mf-model-api)
llms = client.models.llm.list()
chat_out = client.models.invocation.chat(
    model_id="llm-model-id",
    messages=[{"role": "user", "content": "Hello"}],
    stream=False,
)
print(chat_out["text"])

# BKN engine — instance queries and action execution
instances = client.query.instances("bkn-id", "ot-id", limit=20)
result    = client.action_types.execute("bkn-id", "at-id", params={})

# Dataflow automation
from kweaver.resources.dataflows import DataflowStep
result = client.dataflows.execute(
    title="import", steps=[DataflowStep(id="s1", title="load", operator="csv_import")],
)

CLI Quick Reference

kweaver follows a gh-style help layout (see docs/cli_conventions.md §8):

kweaver --help                            # gh-style top-level overview
kweaver help <command>                    # forward to `<command> --help`
kweaver help all                          # full per-action signatures (migration fallback)
kweaver <command> --help                  # subcommand overview + actions
kweaver <command> <subcommand> --help     # action-level flags + examples

Top-level command groups:

AUTHENTICATION & CONFIG  auth · token · config
DECISION AGENT           agent · toolbox · tool
AI DATA PLATFORM         bkn · ds · resource · dataflow · vega · context-loader
TRACE AI                 trace
FOUNDATION               call · explore · model · skill · help

Run kweaver help all for the full per-action signature index (browseable / greppable).

The two CLIs use different top-level command names for some features. The table below maps Python CLI (pip install kweaver-sdk[cli]) to TypeScript CLI (npm install -g @kweaver-ai/kweaver-sdk).

Python CLI TypeScript CLI
kweaver query search <kn_id> <query> kweaver bkn search <kn-id> <query>
kweaver query instances <kn_id> <ot_id> … kweaver bkn object-type query <kn-id> <ot-id> …
kweaver query subgraph <kn_id> … (flags build the path) kweaver bkn subgraph <kn-id> <body-json> (JSON body; shape differs)
kweaver query kn-search <kn_id> <query> (REST, deprecated for schema discovery) kweaver context-loader search-schema <kn-id> <query> for MCP search_schema; kweaver context-loader kn-search <kn-id> <query> is deprecated compatibility only
kweaver action query … / execute / logs … `kweaver bkn action-type query

Only on TypeScript CLI: kweaver vega, kweaver resource list|find|get|query|delete, kweaver ds import-csv, kweaver bkn create-from-csv, and full kweaver agent create/update/delete/publish (see kweaver agent --help). Both CLIs support kweaver config show|list-bd|set-bd and kweaver resource query (Python requires pip install kweaver-sdk[cli]).

Repository Structure (Monorepo)

kweaver-sdk/
├── packages/
│   ├── python/                  # Python SDK + CLI
│   │   ├── src/kweaver/
│   │   │   ├── _client.py       # KWeaverClient
│   │   │   ├── resources/       # knowledge_networks, agents, …
│   │   │   └── cli/             # kweaver commands
│   │   └── tests/
│   └── typescript/              # TypeScript SDK + CLI
│       ├── src/
│       │   ├── client.ts        # KWeaverClient
│       │   ├── resources/       # knowledge-networks, agents, bkn, …
│       │   ├── api/             # low-level HTTP functions
│       │   └── commands/        # CLI command implementations
│       └── test/
├── skills/kweaver-core/         # AI agent skill — KWeaver CLI (SKILL.md)
├── skills/create-bkn/           # AI agent skill — BKN authoring (SKILL.md)
├── docs/
├── README.md                    # English (this file)
└── README.zh.md                 # 中文

Guides

API Reference (HTML)

Generated from source — outputs under docs/reference/ are gitignored.

# Python (pdoc) → docs/reference/python-api-html/index.html
make -C packages/python docs-python

# TypeScript (TypeDoc)
cd packages/typescript
npm install
npm run docs            # English UI → docs/reference/typescript-api-html/
npm run docs:zh         # Chinese UI + README.zh.md → docs/reference/typescript-api-html-zh/
npm run docs:serve      # build + http://127.0.0.1:8766
npm run docs:serve:zh   # build + http://127.0.0.1:8767

# CI: pin "Defined in" links to the build SHA
TYPEDOC_GIT_REVISION=$GITHUB_SHA npm run docs

See docs/README.md for output paths and notes (do not hand-edit anything inside docs/reference/).

Development & Testing

# Python
make -C packages/python test

# TypeScript
make -C packages/typescript test

Using with AI Agents

Install Agent Skills with the skills CLI (npx skills add):

  • Multiple skills from this repo — pass --skill more than once in a single npx skills add (see combined install below).
  • Skills from other repos — run npx skills add <other-repo-url> separately for each repository.
# KWeaver CLI — auth, BKN/KN management, agents, Context Loader
npx skills add https://github.com/kweaver-ai/kweaver-sdk --skill kweaver-core

# BKN authoring — modular BKN v2.0.1 definitions (object/relation/action types, …)
npx skills add https://github.com/kweaver-ai/kweaver-sdk --skill create-bkn

# Install kweaver-core and create-bkn in one command
npx skills add https://github.com/kweaver-ai/kweaver-sdk \
  --skill kweaver-core --skill create-bkn

Before using kweaver-core, authenticate with your KWeaver instance:

npm install -g @kweaver-ai/kweaver-sdk
kweaver auth login https://your-kweaver-instance.com

About

sdk of kweaver for agents

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

19 stars

Watchers

0 watching

Forks

18 forks
Report repository

Releases

38 tags

Packages

 
 
 

Contributors

Languages