veculo 0.2.19

Python SDK for Veculo — AI-native multi-modal graph+vector database

Veculo Python SDK

Python client for Veculo — a managed graph+vector database built on Apache Accumulo.

Installation

pip install veculo

Quick Start

With auto-generated embeddings (easiest)

from veculo import VeculoClient

client = VeculoClient(api_key="vk-...", cluster_id="cl-a7f3b2")

# Insert vertices — Veculo generates embeddings from text automatically
client.put_vertex_with_text(
    id="doc-1",
    text="Q1 revenue exceeded expectations with 40% YoY growth driven by enterprise expansion",
    label="document",
    properties={"author": "Alice", "quarter": "Q1"},
    embed_server_side=True,
)

client.put_vertex_with_text(
    id="doc-2",
    text="Project Plan for Q2 focuses on APAC market entry and partner channel development",
    label="document",
    properties={"author": "Bob", "quarter": "Q2"},
    embed_server_side=True,
)

# Create edges
client.put_edge(source="doc-1", target="doc-2", edge_type="references")

# Ask questions in natural language — answers grounded in your graph
answer = client.rag_query(
    question="What drove Q1 growth and what's planned for Q2?",
    context_hops=2,
)
print(answer["answer"])    # LLM-synthesized answer with citations
print(answer["sources"])   # ["doc-1", "doc-2"]

With your own embeddings

from veculo import VeculoClient

client = VeculoClient(api_key="vk-...", cluster_id="cl-a7f3b2")

# Insert vertices with pre-computed embedding vectors
client.put_vertex(
    id="doc-1",
    label="document",
    properties={"title": "Quarterly Report", "author": "Alice"},
    embedding=[0.12, 0.45, 0.78, 0.33, 0.21, 0.56, 0.89, 0.12],
    visibility="INTERNAL",
)

client.put_vertex(
    id="doc-2",
    label="document",
    properties={"title": "Project Plan", "author": "Bob"},
    embedding=[0.11, 0.44, 0.80, 0.31, 0.19, 0.58, 0.87, 0.14],
)

# Create edges
client.put_edge(
    source="doc-1",
    target="doc-2",
    edge_type="references",
    properties={"section": "appendix"},
)

# Hybrid query: vector similarity + graph traversal
results = client.query(
    embedding=[0.12, 0.44, 0.79, 0.32, 0.15, 0.67, 0.23, 0.91],
    top_k=5,
    edge_type="references",
    depth=2,
    authorizations="INTERNAL",
)

for match in results["results"]:
    print(f"{match['vertex_id']}: {match['score']:.3f}")

Environment Variables

Instead of passing credentials to the constructor, you can set:

Variable	Description
VECULO_API_KEY	API key for authentication
VECULO_ENDPOINT	API endpoint (default: https://api.veculo.com)
VECULO_CLUSTER_ID	Target cluster ID

# With env vars set, no arguments needed:
client = VeculoClient()

CLI

The SDK includes a command-line interface:

# Save connection configuration
veculo connect --endpoint https://api.veculo.com --api-key vk-... --cluster-id cl-a7f3b2

# Check cluster status
veculo status

# Insert a vertex
veculo put-vertex --id alice --label person --property name=Alice --property role=engineer

# Retrieve a vertex
veculo get-vertex --id alice

# Create an edge
veculo put-edge --source alice --target bob --type knows

# Run a hybrid query
veculo query --embedding "0.1,0.2,0.3,0.4" --top-k 10

Configuration is stored in ~/.veculo/config.json.

Error Handling

from veculo import VeculoClient, VeculoError, NotFoundError, AuthenticationError

client = VeculoClient(api_key="vk-...", cluster_id="cl-a7f3b2")

try:
    vertex = client.get_vertex(id="nonexistent")
except NotFoundError:
    print("Vertex does not exist")
except AuthenticationError:
    print("Invalid or expired API key")
except VeculoError as e:
    print(f"API error {e.status_code}: {e.message}")

Visibility Labels

Veculo supports Accumulo-style cell-level security via visibility expressions:

# Write with visibility
client.put_vertex(
    id="doc:internal-report",
    label="document",
    properties={"title": "Q1 Revenue Analysis"},
    visibility="finance&internal",
)

# Read with authorizations
vertex = client.get_vertex(
    id="doc:internal-report",
    authorizations="finance,internal",
)

Embeddings

Veculo supports multiple ways to generate vector embeddings:

Client-side (bring your own API key)

from veculo import VeculoClient
from veculo.embeddings import OpenAIEmbeddings

client = VeculoClient(api_key="vk-...", cluster_name="production")
client.set_embedder(OpenAIEmbeddings(api_key="sk-..."))

# Automatically generates embedding from text
client.put_vertex_with_text(
    id="doc:report-q1",
    text="Q1 revenue exceeded expectations with 40% YoY growth",
    label="document",
    properties={"quarter": "Q1", "year": "2026"},
)

Other providers:

from veculo.embeddings import VertexAIEmbeddings, SentenceTransformerEmbeddings

# Vertex AI
client.set_embedder(VertexAIEmbeddings(project="my-project"))

# Local (no API key needed)
client.set_embedder(SentenceTransformerEmbeddings())

Install extras: pip install 'veculo[openai]', pip install 'veculo[vertexai]', or pip install 'veculo[local]'

Server-side (Veculo-managed, billed separately)

# Veculo generates the embedding for you server-side
client.put_vertex_with_text(
    id="doc:report-q1",
    text="Q1 revenue exceeded expectations",
    label="document",
    embed_server_side=True,  # billed per request
)

Multi-Modal Knowledge Graphs

Upload any file — Veculo automatically extracts text, generates embeddings, discovers entities, and builds a knowledge subgraph.

Supported file types

Type	What Veculo extracts
PDF	Text, citations, entities, embeddings
Images	Visual description, objects, entities, embeddings
Audio	Transcript, entities, embeddings
Video	Audio transcript, entities, embeddings
Code	Functions, classes, imports, embeddings

Upload a file

# Upload a PDF — Veculo does the rest
client.put_vertex_with_file(
    id="paper:arxiv-2401",
    file_path="attention-is-all-you-need.pdf",
    label="paper",
    properties={"source": "arxiv"},
)

# Upload an image
client.put_vertex_with_file(
    id="img:brain-scan-001",
    file_path="brain-scan.png",
    label="medical-image",
)

# Upload source code
client.put_vertex_with_file(
    id="code:transformer",
    file_path="transformer.py",
    label="code",
)

Check extraction status

jobs = client.list_jobs()
for job in jobs["jobs"]:
    print(f"{job['vertex_id']}: {job['status']}")

CLI

veculo upload --id paper-1 --file paper.pdf --label paper
veculo jobs
veculo get-vertex --id paper-1

AI-Native Queries

Natural Language Query

Ask questions in plain English — the SDK translates them into graph queries via LLM:

result = client.nl_query(
    question="Which documents reference the Q1 report?",
    authorizations="internal",
)

print(result["query_plan"]["explanation"])
for step_result in result["results"]:
    print(step_result)

Graph-Augmented RAG

Retrieval-Augmented Generation that combines vector search with graph context:

answer = client.rag_query(
    question="What were the key findings in the Q1 analysis?",
    context_hops=2,          # expand graph 2 hops for richer context
    model="claude-sonnet-4-20250514",  # optional model override
    top_k=10,
)

print(answer["answer"])
print("Sources:", answer["sources"])  # vertex IDs cited

SSM Reasoning (Stateful Multi-Hop Traversal)

Follow semantic threads through your graph. Unlike BFS/DFS, the SSM accumulates context at each hop — the hidden state guides which edge to follow next:

# Text query — server generates the embedding
result = client.reason(
    query="how did neural networks evolve into large language models",
    max_depth=5,
    alpha=0.8,      # high momentum — remember the journey
    threshold=0.2,  # low threshold — keep following
)

for hop in result["path"]:
    print(f"  {hop['vertex_id']} (score: {hop['score']:.4f})")
print(f"Terminated: {result['termination_reason']}")

# Start from a specific vertex
result = client.reason(
    query="trace the influence chain",
    start_vertex="ai-foundations",
    max_depth=10,
)

The alpha parameter controls state momentum:

• alpha=0.9 — heavy history, follows long conceptual threads
• alpha=0.5 — balanced, adapts quickly to new context
• alpha=0.1 — almost stateless, similar to greedy nearest-neighbor

Reasoning queries run on dedicated scan servers (Accumulo 4.0) in an isolated inference resource group — zero impact on write throughput.

CLI

veculo reason --embedding "0.1,0.2,..." --max-depth 5 --alpha 0.8
veculo reason --embedding "0.1,0.2,..." --start-vertex ai-foundations

Temporal Queries

Filter edges by time range — either write time (when the edge was stored) or event time (a user-supplied timestamp):

# Trades executed in the last 7 days
import time
week_ago = int((time.time() - 7 * 86400) * 1000)

result = client.query_temporal(
    vertex_id="portfolio-global-macro",
    start_time=week_ago,
    edge_type="TRADED",
    time_field="write_time",  # or "event_time" for user-supplied timestamps
)

for edge in result["edges"]:
    print(f"  {edge['direction']} {edge['type']} → {edge.get('target', edge.get('source'))}")

CLI

veculo temporal --id portfolio-global-macro --start-time 1700000000000 --edge-type TRADED
veculo temporal --id portfolio-global-macro --time-field event_time --start-time 1700000000000

Aggregation Queries

Server-side aggregation — counts, grouping, and statistics computed inside Accumulo without pulling data to the client:

# Count edges by type for a vertex
result = client.aggregate(
    aggregation="GROUP_BY_EDGE_TYPE",
    vertex_id="entity-acme-corp",
)
for group in result["results"]:
    print(f"  {group['group']}: {group.get('count', 0)}")

# Degree (in + out connections)
result = client.aggregate(aggregation="DEGREE", vertex_id="entity-acme-corp")

# Group trades by day
result = client.aggregate(
    aggregation="GROUP_BY_TIME",
    vertex_id="entity-acme-corp",
    edge_type="TRADED",
    time_bucket="DAY",
)

# Most connected entities in the graph
result = client.aggregate(aggregation="TOP_CONNECTED", limit=10)

# Count distinct counterparties
result = client.aggregate(
    aggregation="COUNT_DISTINCT",
    vertex_id="entity-acme-corp",
    edge_type="TRANSACTED_WITH",
)

Aggregation types: COUNT, COUNT_DISTINCT, GROUP_BY_EDGE_TYPE, GROUP_BY_TIME, DEGREE, TOP_CONNECTED

CLI

veculo aggregate --aggregation GROUP_BY_EDGE_TYPE --id entity-acme-corp
veculo aggregate --aggregation GROUP_BY_TIME --id entity-acme-corp --time-bucket DAY
veculo aggregate --aggregation TOP_CONNECTED --limit 10

Graph Pattern Queries

Structural queries that traverse the graph to find paths, intersections, and triangles:

Find Paths

# Shortest path between two entities
result = client.find_path(source="entity-acme-corp", target="entity-treasury-bonds")
for path in result["paths"]:
    print(" → ".join(path))

# All paths (up to 10)
result = client.find_path(
    source="entity-acme-corp",
    target="entity-treasury-bonds",
    edge_type="HOLDS",
    max_depth=4,
    find_all=True,
    max_paths=10,
)

Find Intersection

Find vertices connected to ALL anchor vertices — e.g., "which funds hold positions in both AAPL and MSFT?":

result = client.find_intersection(
    anchor_vertices=["security-aapl", "security-msft"],
    edge_types=["HOLDS"],
    direction="incoming",  # who holds both securities
)
print(f"Funds holding both: {result['vertices']}")

Find Triangles

Discover triangular relationships — useful for detecting circular exposures and concentration risk:

result = client.find_triangles(
    vertex_id="entity-acme-corp",
    edge_type="TRANSACTED_WITH",
    max_triangles=50,
)
for triangle in result["triangles"]:
    print(f"  {' — '.join(triangle)}")

CLI

veculo find-path --source entity-acme-corp --target entity-treasury-bonds
veculo find-path --source entity-acme-corp --target entity-treasury-bonds --find-all --max-depth 4
veculo find-intersection --anchors security-aapl security-msft --edge-type HOLDS --direction incoming
veculo find-triangles --id entity-acme-corp --edge-type TRANSACTED_WITH

Bulk Operations

Insert many vertices or edges in a single batch:

client.put_vertices_bulk([
    {"id": "doc:1", "label": "document", "properties": {"title": "Report A"}},
    {"id": "doc:2", "label": "document", "properties": {"title": "Report B"}},
    {"id": "doc:3", "label": "document", "properties": {"title": "Report C"}},
])

client.put_edges_bulk([
    {"source": "doc:1", "target": "doc:2", "edge_type": "references"},
    {"source": "doc:2", "target": "doc:3", "edge_type": "references"},
])

Hibernate / Resume

Stop compute costs while preserving all data in storage:

# Hibernate — flushes tables, snapshots metadata, tears down compute
client.hibernate()
# Storage continues at ~$0.02/GB/month, compute costs stop immediately

# Later — resume with all data intact
client.resume()

Data, metadata, embeddings, and edges are all preserved. Only compute is stopped.

Configuration

Auto-Embed

Enable automatic embedding generation for new text vertices:

client.configure_auto_embed(
    model="text-embedding-005",
    text_properties=["description", "content"],
)

Semantic Edges

Enable automatic similarity edge creation during compaction:

client.configure_semantic_edges(
    similarity_threshold=0.85,
    max_edges_per_vertex=10,
)

Insights

Query AI-derived analytics:

# Anomalous vertices (outliers by embedding distance)
anomalies = client.get_anomalies(authorizations="internal")

# Top vertices by PageRank
ranks = client.get_top_ranked()

# Pending processing queue status
status = client.get_processing_status()
print(f"Embeddings pending: {status['auto_embed']}")

AI Reasoning Lab

Advanced graph reasoning powered by state space models, graph neural networks, and hyperbolic geometry.

SSM Reasoning

# Basic SSM reasoning — follows paths through the graph guided by a hidden state
result = client.reason(query="what drove Q3 revenue decline?", start_vertex="report-q3")
for hop in result["path"]:
    print(f"  {hop['vertex_id']} (score: {hop['score']:.3f})")

Multi-Agent Reasoning

# Run multiple reasoning strategies in parallel and measure agreement
result = client.reason_multi_agent(
    query="what drove Q3 revenue decline?",
    strategies=["root_cause", "knowledge", "influence"],
    max_depth=8,
)
print(f"Confidence: {result['confidence']:.0%}")
print(f"Agreed vertices: {result['agreed_vertices']}")
print(f"Divergent vertices: {result['divergent_vertices']}")

Adversarial Verification

# Verify a claim by running support and contradiction agents
result = client.verify_adversarial(
    query="ACME Corp's exposure to interest rate risk exceeds $2B",
    start_vertex="filing-10k-acme",
)
print(f"Verdict: {result['verdict']}")  # SUPPORTED, CONTESTED, or UNSUPPORTED
print(f"Trust score: {result['trust_score']:.0%}")
print(f"Spread kappa={result['kappa']:.3f} ({result['geometric_regime']})")

Temporal SSM

# Reasoning with time-decay — recent data gets more weight
result = client.reason_temporal(
    query="recent changes to portfolio allocation",
    recent_window_hours=48,
    max_depth=10,
)

Graph Attention

# Multi-head attention across a vertex's neighborhood
result = client.attend(
    query="emerging market equities",
    vertex_id="sector-em-equities",
    top_k=10,
)
for v in result["attended_vertices"]:
    print(f"  {v['vertex_id']} (attention: {v['attention_score']:.3f})")

Causal Inference

# Trace causes forward (what did X cause?)
effects = client.trace_causes(
    query="Fed rate hike",
    start_vertex="event-fed-rate-2024-03",
    max_depth=5,
)

# Trace causes backward (what caused X?)
causes = client.trace_caused_by(
    query="margin call",
    start_vertex="alert-margin-call-042",
)

GNN Message Passing

# Graph neural network propagation — aggregates neighbor information
result = client.gnn_propagate(
    query="counterparty credit exposure",
    start_vertex="entity-counterparty-a",
    rounds=3,       # aggregation rounds
    top_k=10,
    self_weight=0.7, # 70% self, 30% neighbors
)

Rule-Based Inference

# Apply logical rules to infer new edges
result = client.infer_edges(
    start_vertex="fund-global-macro",
    rules=[
        {"antecedent": ["HOLDS", "ISSUED_BY"], "consequent": "EXPOSED_TO", "min_confidence": 0.5},
        {"antecedent": ["BENCHMARKED_TO", "CONTAINS"], "consequent": "INDIRECTLY_TRACKS", "min_confidence": 0.4},
    ],
    max_inferences=50,
)
for edge in result["inferred_edges"]:
    print(f"  {edge['source']} --{edge['edge_type']}--> {edge['target']}")

# Discover rules from graph structure
rules = client.discover_rules(max_rules=10, sample_size=500)
for rule in rules["rules"]:
    print(f"  {rule['antecedent']} => {rule['consequent']} (conf: {rule['confidence']:.2f})")

Hyperbolic Search

# Search using hyperbolic geometry — naturally captures hierarchy
result = client.hyperbolic_search(
    query="fixed income derivatives",
    top_k=10,
)
for match in result["matches"]:
    depth = "ancestor" if match["is_ancestor"] else "descendant"
    print(f"  {match['vertex_id']} (depth: {match['hierarchy_depth']:.2f}, {depth})")

Embedding Evolution

# Track how a vertex's embedding has changed over time
result = client.track_evolution("entity-acme-corp", max_versions=10)
if result["significant"]:
    print(f"Embedding drifted {result['total_drift']:.4f} — ACME's risk profile has shifted")

Neighborhood Enrichment

# Enrich embeddings based on graph neighborhood (run periodically)
result = client.enrich_embeddings(learning_rate=0.2, max_neighbors=50)
print(f"Enriched {result['vertices_enriched']} vertices")

Graph Compilation

# Pre-compute frequently traversed reasoning paths
result = client.compile_frequent_paths(min_frequency=3, min_confidence=0.5)
print(f"Compiled {result['compiled_count']} paths")

License

Apache License 2.0