# Veculo Python SDK

Python client for [Veculo](https://veculo.com) — a managed graph+vector database built on Apache Accumulo.

## Installation

```bash
pip install veculo
```

## Quick Start

```python
from veculo import VeculoClient

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

# Insert vertices with vector embeddings
client.put_vertex(
    id="doc-1",
    label="document",
    properties={"title": "Quarterly Report", "author": "Alice"},
    embedding=[0.12, 0.45, 0.78, 0.33, ...],  # your embedding vector
    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, ...],
)

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

# Retrieve a vertex
vertex = client.get_vertex(id="doc-1")
print(vertex)

# Hybrid query: vector similarity + graph traversal
results = client.query(
    embedding=[0.12, 0.44, 0.79, 0.32, ...],  # query vector
    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 |

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

## CLI

The SDK includes a command-line interface:

```bash
# 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

```python
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:

```python
# 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",
)
```

## License

Apache License 2.0
