Metadata-Version: 2.4
Name: vetgraph
Version: 0.1.0
Summary: Transform unstructured text into NetworkX knowledge graphs using LLMs
Project-URL: Homepage, https://github.com/yourusername/vetgraph
Project-URL: Documentation, https://github.com/yourusername/vetgraph#readme
Project-URL: Repository, https://github.com/yourusername/vetgraph
Project-URL: Issues, https://github.com/yourusername/vetgraph/issues
Author-email: Vishesh Raju <visheshinus@gmail.com>
License: MIT
License-File: LICENSE
Keywords: graph,knowledge-graph,llm,networkx,nlp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: instructor>=1.0.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyvis>=0.3.0
Provides-Extra: all-providers
Requires-Dist: anthropic>=0.18.0; extra == 'all-providers'
Requires-Dist: google-genai>=0.2.0; extra == 'all-providers'
Requires-Dist: openai>=1.0.0; extra == 'all-providers'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=0.2.0; extra == 'gemini'
Provides-Extra: ollama
Requires-Dist: openai>=1.0.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# VetGraph

**Transform unstructured text into NetworkX knowledge graphs using LLMs**

VetGraph is a provider-agnostic Python library that leverages Large Language Models (OpenAI, Anthropic, Gemini, Ollama) to extract entities and relationships from unstructured text and construct knowledge graphs using NetworkX.

## 🚀 Features

- 🤖 **Provider-Agnostic**: Works with OpenAI, Anthropic (Claude), Google Gemini, Ollama, and Azure OpenAI
- 📊 **NetworkX Integration**: Builds standard NetworkX graphs for powerful graph analysis
- 🎨 **Dual Visualization**: Static plots with matplotlib and interactive HTML visualizations with pyvis
- ✅ **Type Safety**: Pydantic models with instructor for robust structured outputs
- 🔧 **Flexible**: Schema-constrained extraction and multiple export formats

## 📦 Installation

```bash
# Install with OpenAI support
pip install vetgraph[openai]

# Install with Anthropic support
pip install vetgraph[anthropic]

# Install with Gemini support  
pip install vetgraph[gemini]

# Install with all providers
pip install vetgraph[all-providers]

# Basic installation (bring your own LLM client)
pip install vetgraph
```

## 🎯 Quick Start

### Using OpenAI

```python
from vetgraph import VetGraph

# Initialize with OpenAI
vg = VetGraph.from_openai(api_key="sk-...")

# Extract knowledge from text
text = """
Albert Einstein was a theoretical physicist who developed the theory of relativity.
He was born in Germany and later moved to the United States. Einstein worked at
Princeton University and won the Nobel Prize in Physics in 1921.
"""

result = vg.add_text(text)
print(f"Extracted {result.get_triple_count()} triples")

# Visualize the graph
vg.visualize("einstein_graph.html")
```

### Using Anthropic Claude

```python
from vetgraph import VetGraph

vg = VetGraph.from_anthropic(
    api_key="sk-ant-...",
    model="claude-3-5-sonnet-20241022"
)

result = vg.add_text("Marie Curie discovered radium and polonium.")
```

### Using Google Gemini

```python
from vetgraph import VetGraph

vg = VetGraph.from_gemini(
    api_key="...",
    model="gemini-2.5-flash"
)

result = vg.add_text("The Eiffel Tower is located in Paris, France.")
```

### Using Ollama (Local, Free!)

```python
from vetgraph import VetGraph

vg = VetGraph.from_ollama(model="llama3.2")
result = vg.add_text("Python was created by Guido van Rossum.")
```

## 📚 Usage Examples

### Schema-Constrained Extraction

```python
from vetgraph import VetGraph

vg = VetGraph.from_openai(api_key="sk-...")

# Define allowed relationship types
schema = ["works_for", "located_in", "developed_by", "invented"]

result = vg.add_text(
    "Steve Jobs co-founded Apple in Cupertino.",
    schema=schema
)
```

### Graph Analysis with NetworkX

```python
import networkx as nx

# Get the NetworkX graph
graph = vg.get_graph()

# Use NetworkX algorithms
centrality = nx.degree_centrality(graph)
print("Most central nodes:", 
      sorted(centrality.items(), key=lambda x: x[1], reverse=True)[:5])

# Find shortest path
if nx.has_path(graph, "Einstein", "Princeton"):
    path = nx.shortest_path(graph, "Einstein", "Princeton")
    print("Path:", " -> ".join(path))
```

### Graph Statistics

```python
stats = vg.get_statistics()
print(f"Nodes: {stats['nodes']}")
print(f"Edges: {stats['edges']}")
print(f"Density: {stats['density']:.3f}")
print(f"Connected: {stats['is_connected']}")
print(f"Unique relations: {stats['unique_relations']}")
```

### Visualization Options

```python
# Interactive HTML visualization (default)
vg.visualize("graph.html")

# Using pyvis directly for more control
net = vg.visualize_interactive(
    output_file="custom_graph.html",
    height="800px",
    width="100%",
    notebook=False
)

# Matplotlib visualization
vg.visualize_matplotlib(
    figsize=(15, 10),
    node_color="lightcoral",
    node_size=4000,
    save_path="graph.png"
)
```

### Saving and Loading Graphs

```python
# Save graph in various formats
vg.save_graph("my_graph.json", format="json")          # Node-link JSON
vg.save_graph("my_graph.graphml", format="graphml")    # GraphML (XML)
vg.save_graph("my_graph.gexf", format="gexf")          # GEXF (for Gephi)
vg.save_graph("my_graph.edgelist", format="edgelist")  # Edge list

# Load a saved graph
vg.load_graph("my_graph.json", format="json")
```

## 🔧 Advanced Usage

### Custom Provider Configuration

```python
from vetgraph import VetGraph, create_openai_client

# Create a custom client with specific settings
client = create_openai_client(
    api_key="sk-...",
    base_url="https://custom-endpoint.com/v1"
)

# Use it with VetGraph
vg = VetGraph(client=client, model="gpt-4o-mini")
```

### Azure OpenAI

```python
vg = VetGraph.from_azure_openai(
    api_key="your-azure-key",
    azure_endpoint="https://your-resource.openai.azure.com/",
    model="gpt-4-deployment-name",
    api_version="2024-02-01"
)
```

### Batch Processing

```python
texts = [
    "Leonardo da Vinci painted the Mona Lisa.",
    "The Mona Lisa is displayed in the Louvre Museum.",
    "The Louvre Museum is located in Paris."
]

for text in texts:
    vg.add_text(text)

# All extractions are added to the same graph
print(f"Total nodes: {vg.graph.number_of_nodes()}")
print(f"Total edges: {vg.graph.number_of_edges()}")
```

## 🛠️ API Reference

### VetGraph Class

**Factory Methods:**
- `VetGraph.from_openai(api_key, model="gpt-4o-mini")` - Create instance with OpenAI
- `VetGraph.from_anthropic(api_key, model="claude-3-5-sonnet-20241022")` - Create with Anthropic
- `VetGraph.from_gemini(api_key, model="gemini-2.5-flash")` - Create with Gemini
- `VetGraph.from_ollama(model="llama3.2")` - Create with Ollama
- `VetGraph.from_azure_openai(...)` - Create with Azure OpenAI

**Core Methods:**
- `add_text(text, schema=None, temperature=0.3)` - Extract triples from text
- `get_graph()` - Get the NetworkX DiGraph
- `clear_graph()` - Clear all nodes and edges
- `get_statistics()` - Get graph statistics

**Visualization:**
- `visualize(output_path="graph.html")` - Create interactive HTML visualization
- `visualize_interactive(...)` - Create pyvis visualization with options
- `visualize_matplotlib(...)` - Create matplotlib visualization

**Persistence:**
- `save_graph(output_path, format="json")` - Export graph to file
- `load_graph(input_path, format="json")` - Load graph from file

## 📊 Supported Models (as of March 2026)

**OpenAI:**
- `gpt-4o-mini` (default, recommended)
- `gpt-4o`
- `gpt-4-turbo`

**Anthropic:**
- `claude-3-5-sonnet-20241022` (default, recommended)
- `claude-3-5-haiku-20241022`
- `claude-3-opus-20240229`

**Google Gemini:**
- `gemini-2.5-flash` (default, recommended)
- `gemini-2.5-pro`
- `gemini-2.0-flash`

**Ollama:**
- `llama3.2` (default)
- `llama3.1`
- `mistral`
- `mixtral`
- Any other installed Ollama model

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see LICENSE file for details.

## 🙏 Acknowledgments

Built with:
- [instructor](https://github.com/jxnl/instructor) - Structured outputs for LLMs
- [NetworkX](https://networkx.org/) - Graph analysis
- [Pyvis](https://pyvis.readthedocs.io/) - Interactive visualizations
- [Pydantic](https://docs.pydantic.dev/) - Data validation

## 📧 Contact

- **Author:** Vishesh Raju
- **Email:** visheshinus@gmail.com
- **GitHub:** [github.com/Vishesh0-7/vetgraph](https://github.com/Vishesh0-7/vetgraph)
