Metadata-Version: 2.4
Name: astraeadb
Version: 0.1.1
Summary: Python client for the AstraeaDB graph database with vector search
Project-URL: Homepage, https://github.com/AstraeaDB/astraeadb-python
Project-URL: Repository, https://github.com/AstraeaDB/astraeadb-python
Project-URL: Issues, https://github.com/AstraeaDB/astraeadb-python/issues
Project-URL: AstraeaDB server, https://github.com/AstraeaDB/AstraeaDB-Official
Author-email: James Harris <jimeharrisjr@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: astraeadb,database,graph,graph-database,graphrag,knn,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: pandas>=1.5; extra == 'all'
Requires-Dist: pyarrow>=14; extra == 'all'
Provides-Extra: arrow
Requires-Dist: pyarrow>=14; extra == 'arrow'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Description-Content-Type: text/markdown

# astraeadb

[![CI](https://github.com/AstraeaDB/astraeadb-python/actions/workflows/ci.yml/badge.svg)](https://github.com/AstraeaDB/astraeadb-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/astraeadb.svg)](https://pypi.org/project/astraeadb/)
[![Python versions](https://img.shields.io/pypi/pyversions/astraeadb.svg)](https://pypi.org/project/astraeadb/)

Python client for [AstraeaDB](https://github.com/AstraeaDB/AstraeaDB-Official), a
graph database with vector search written in Rust. Talks to the AstraeaDB
server over newline-delimited JSON-over-TCP (no dependencies) with an optional
[Apache Arrow Flight](https://arrow.apache.org/docs/format/Flight.html)
transport and pandas integration.

## Installation

```bash
pip install astraeadb                 # core client, zero dependencies
pip install "astraeadb[arrow]"        # + Arrow Flight transport (pyarrow)
pip install "astraeadb[pandas]"       # + DataFrame helpers (pandas)
pip install "astraeadb[all]"          # everything
```

Requires Python 3.9+. A running AstraeaDB server is required — see the
[AstraeaDB documentation](https://github.com/AstraeaDB/AstraeaDB-Official).

## Quick start

```python
from astraeadb import AstraeaClient

with AstraeaClient(host="127.0.0.1", port=7687) as client:
    alice = client.create_node(["Person"], {"name": "Alice", "age": 30})
    bob = client.create_node(["Person"], {"name": "Bob"})
    client.create_edge(alice, bob, "KNOWS", weight=0.9)

    # Traversals
    client.bfs(alice, max_depth=2)
    client.dfs(alice, max_depth=2)
    client.shortest_path(alice, bob, weighted=True)

    # Lookups
    client.find_by_label("Person")
    client.find_edge_by_type("KNOWS")

    # Vector similarity (results carry node_id + distance; smaller is closer)
    hits = client.vector_search([0.1, 0.9, 0.3], k=5)

    # Graph algorithms (computed server-side)
    client.run_pagerank()
    client.run_louvain()
    client.run_betweenness_centrality()

    # GQL
    client.query("MATCH (p:Person) RETURN p.name")
```

## Features

- **CRUD** — create/read/update/delete nodes and edges with arbitrary properties
- **Lookups** — `find_by_label`, `find_edge_by_type`, bulk `delete_by_label`
- **Traversals** — `bfs`, `dfs`, `shortest_path`, `neighbors`
- **Temporal queries** — time-travel variants (`bfs_at`, `dfs_at`,
  `neighbors_at`, `shortest_path_at`) over edge validity windows
- **Graph algorithms** — `run_pagerank`, `run_louvain`,
  `run_connected_components`, `run_degree_centrality`,
  `run_betweenness_centrality`
- **Vector search** — `vector_search` (k-NN), `hybrid_search` (graph + vector),
  `semantic_neighbors`, `semantic_walk`
- **GraphRAG** — `extract_subgraph` and `graph_rag` for LLM context assembly
- **Statistics** — `graph_stats` and raw `get_subgraph` export
- **GQL** — `query` for Cypher-style graph queries
- **Batch** — `create_nodes`, `create_edges`, `delete_nodes`, `delete_edges`
- **DataFrames** — import/export helpers in `astraeadb.dataframe` (pandas)
- **Arrow Flight** — high-throughput columnar transport when `pyarrow` is
  installed

## Clients

| Class | Transport | Notes |
|-------|-----------|-------|
| `JsonClient` | JSON/TCP | Always available, zero dependencies |
| `ArrowClient` | Arrow Flight | Requires `pyarrow`; high-throughput bulk/query |
| `AstraeaClient` | Auto-select | Uses Arrow when available, falls back to JSON |

```python
from astraeadb import JsonClient       # explicit JSON/TCP
from astraeadb import ArrowClient      # explicit Arrow Flight (needs pyarrow)
from astraeadb import AstraeaClient    # unified, auto-selecting
```

## License

[MIT](LICENSE) © 2026 James Harris.
