Metadata-Version: 2.4
Name: python-arango-ai-sdk
Version: 0.1.0
Summary: Python SDK for ArangoDB AutoGraph and AutoRAG
Author-email: ArangoDB <info@arangodb.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/arangodb/python-arango-ai-sdk
Project-URL: Repository, https://github.com/arangodb/python-arango-ai-sdk
Project-URL: Documentation, https://github.com/arangodb/python-arango-ai-sdk#readme
Project-URL: Issues, https://github.com/arangodb/python-arango-ai-sdk/issues
Keywords: arangodb,graphrag,autograph,knowledge-graph,rag,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Dynamic: license-file

# python-arango-ai-sdk

Python SDK for ArangoDB AutoGraph and AutoRAG. Build knowledge graphs that connect the dots across your documents — then query them with natural language.

## Installation

```bash
pip install python-arango-ai-sdk
```

## Prerequisites

1. **ArangoDB Contextual Data Platform** — a running instance, locally or remotely.
   See [arango.ai](https://arango.ai/) for setup instructions.
2. **LLM API key** — [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://console.anthropic.com/), or any compatible provider.
3. **Python 3.10+**

Set your credentials as environment variables:

```bash
export ARANGODB_PASSWORD=your-password
export LLM_API_KEY=sk-your-openai-key
```

## Quick Start

Upload separate documents and ask questions that connect them — the knowledge
graph discovers relationships across documents automatically.

```python
import os
from arango_ai import ArangoAIClient

client = ArangoAIClient('https://localhost:8529', verify_tls=False)
db = client.db('my_database', username='root', password=os.environ['ARANGODB_PASSWORD'])
ag = db.autograph('my-project', llm_api_key=os.environ['LLM_API_KEY'])

# Upload separate documents about different people
ag.upload(text='Einstein developed the theory of relativity and collaborated with Bohr...')
ag.upload(text='Niels Bohr proposed the Bohr model of the atom and mentored Heisenberg...')
ag.upload(text='Heisenberg formulated the uncertainty principle, studied under Bohr...')

ag.build()

# Ask a question that connects information across all three documents
print(ag.ask('How are Einstein, Bohr, and Heisenberg connected to each other?'))
```

## Query Modes

```python
ag.ask('Tell me about Einstein.')                            # local/hybrid (default)
ag.ask('What are the big themes here?', mode='global')       # whole-graph summary
ag.ask('Explain the photoelectric effect.', mode='unified')  # passages + entities
ag.ask('How are these people connected?',
       use_llm_planner=True)                                 # multi-hop reasoning
```

## Examples

Run the examples in order:

```bash
# 1. Build a KG from inline text (~10-15 min build time)
ARANGODB_PASSWORD=test LLM_API_KEY=sk-... python examples/quickstart.py

# 2. Build a medical KG with sample queries
ARANGODB_PASSWORD=test LLM_API_KEY=sk-... python examples/medical_corpus.py

# 3. Try all query modes (run medical_corpus.py first)
ARANGODB_PASSWORD=test LLM_API_KEY=sk-... python examples/query_modes.py

# 4. Reconnect without rebuilding (run medical_corpus.py first)
ARANGODB_PASSWORD=test LLM_API_KEY=sk-... python examples/reconnect.py

# 5. Context manager with auto-cleanup (run medical_corpus.py first)
ARANGODB_PASSWORD=test LLM_API_KEY=sk-... python examples/context_manager.py
```

## Documentation

- [Getting Started](docs/getting-started.rst)
- [Architecture](docs/architecture.rst)
- [API Reference](docs/api.rst)
- [Examples](docs/examples.rst)
- [Error Handling](docs/error-handling.rst)
- [Troubleshooting](docs/troubleshooting.rst)
- [Contributing](CONTRIBUTING.md)

## License

[Apache 2.0](LICENSE)
