cortex-client

Thin Python client for Cortex — the rapid web cartographer for AI agents.

Install

pip install cortex-client

Requires the Cortex runtime. Install with: cargo install cortex-runtime The daemon starts automatically on first use.

Quick Start

import cortex_client

# Map a website into a navigable graph
site = cortex_client.map("amazon.com")
print(f"Mapped {len(site.nodes)} pages, {len(site.edges)} links")

# Find products under $300
products = site.filter(page_type=0x04, features={48: {"lt": 300}}, limit=10)
for p in products:
    print(f"  {p.url}  price={p.features[48]}")

# Find the shortest path between two pages
path = site.pathfind(0, products[0].index)
print(f"Path: {' → '.join(str(n) for n in path.nodes)}")

Page Types

Use these codes with page_type= filters:

Feature Dimensions

Each page has a 128-dimensional feature vector. Key dimensions:

API Reference

Map & Query

# Map a single site
site = cortex_client.map("github.com")

# Map multiple sites
sites = cortex_client.map_many(["amazon.com", "ebay.com"])

# Filter by type + features
products = site.filter(page_type=0x04, features={52: {"gt": 4.0}})

# Pathfind between pages
path = site.pathfind(from_node=0, to_node=42)

# Similarity search
similar = site.similar(node_index=5, limit=10)

Cross-Site Comparison

result = cortex_client.compare(["amazon.com", "ebay.com", "walmart.com"])
print(result.common_types)   # Shared page types
print(result.unique_types)   # Per-site unique types

Single Page Analysis

page = cortex_client.perceive("https://example.com/product/123")
print(page.page_type, page.features, page.actions)

Authentication

session = cortex_client.login("example.com", username="user", password="pass")
site = cortex_client.map("example.com", session=session)

Error Handling

from cortex_client import CortexConnectionError, CortexMapError, CortexTimeoutError

try:
    site = cortex_client.map("example.com")
except CortexConnectionError:
    print("Cortex daemon not running. Start with: cortex start")
except CortexTimeoutError:
    print("Mapping took too long. Try a smaller site or increase timeout.")
except CortexMapError as e:
    print(f"Mapping failed: {e}")

License

Apache-2.0