Skip to main content

Python SDK & CLI

The official Veezoo Python SDK provides a Python client library and a command-line tool (vz / veezoo) for scripting against the Veezoo API.

Installation​

pip install veezoo

Optional extras:

pip install 'veezoo[pandas]'       # pandas DataFrame support
pip install 'veezoo[interactive]'  # rich REPL with syntax highlighting
pip install 'veezoo[all]'          # everything

Python 3.9+ is required.

Authentication​

All requests use a Veezoo API key. Create one under Admin > API > API Keys; the key inherits the access of the user it is assigned to, so its knowledge-graph and role permissions follow that user's.

Configure the key in any of three ways:

# Interactive (stored in ~/.veezoo/config.json)
vz configure

# Non-interactive
vz configure --api-key YOUR_API_KEY --kg-id my-default-kg

# Environment variables (override config file)
export VEEZOO_API_KEY=your-api-key
export VEEZOO_KG_ID=my-knowledge-graph

To see the current config: vz config. To clear it: vz logout.

CLI Quickstart​

The CLI can be invoked as either veezoo or the shorter vz.

Test the connection​

vz ping

Ask a natural-language question​

vz ask "How many customers do we have?" --kg-id my-kg

Common flags:

  • --conversation-id <id> — continue a previous conversation for follow-ups.
  • --language en|de|… — override the knowledge graph's default language.
  • --format table|json|csv — render answer tables in a different format.
  • --show-vql / --show-sql — print the generated VQL / SQL.
  • --raw — dump the full raw API response as JSON.

Run a VQL query​

vz query "var c from kb.Customer; select(count(c))" --kg-id my-kg

# From a file
vz query -i my-query.vql --kg-id my-kg

# From stdin
echo "select(count(kb.Customer))" | vz query --kg-id my-kg

Output formats: --format table (default), --format json, --format csv.

Run a shared answer​

vz shared-answer SHARED_ANSWER_ID --kg-id my-kg

Interactive mode​

A REPL with syntax highlighting, auto-completion, and multi-line editing:

pip install 'veezoo[interactive]'
vz interactive --kg-id my-kg   # or: vz i -g my-kg

The REPL has two modes — ask (default) for natural-language questions and vql for VQL queries. Use .mode to toggle, .help to list all commands, .exit to quit.

Python Library Quickstart​

from veezoo import VeezooClient

client = VeezooClient(api_key="your-api-key")

# Natural-language question
answer = client.ask(
    kg_id="my-kg",
    question="How many customers do we have?",
)
for message in answer.messages:
    print(message)

# VQL query
result = client.run_vql_query(
    kg_id="my-kg",
    vql="var c from kb.Customer; select(count(c))",
)
for row in result.data:
    print(row.values())

Working with pandas​

pip install 'veezoo[pandas]'
result = client.run_vql_query(
    kg_id="my-kg",
    vql="var c from kb.Customer; select(c)",
)
df = result.data.to_dataframe()
df.head()

Conversations​

Follow-up questions share context when you reuse a conversation_id:

first = client.ask(kg_id="my-kg", question="How many customers do we have?")
followup = client.ask(
    kg_id="my-kg",
    question="Break down by region",
    conversation_id=first.conversation_id,
)

Reference​

  • Source and full API reference: sdks/python/README.md
  • REST API reference: the API section of these docs (if available for your plan) or contact Veezoo for access.
  • For AI-assistant integration see MCP.