# FlowgentraAI Python Bindings

Python bindings for the [FlowgentraAI](https://github.com/oussamabenhariz/FlowgentraAI) Rust library, built with [PyO3](https://pyo3.rs) + [maturin](https://www.maturin.rs).

## Installation

### From source (development)

```bash
cd flowgentra-ai-py
pip install maturin
maturin develop
```

### Build a wheel

```bash
maturin build --release
pip install target/wheels/flowgentra_ai-*.whl
```

## Quick Start

```python
from flowgentra_ai import Agent, SharedState, Message

# Create agent from YAML config
agent = Agent.from_config_path("config.yaml")

# Set initial state
agent.state["input"] = "Hello, world!"

# Run the agent
result = agent.run()
print(result.to_dict())
```

## API Overview

### State Management

```python
from flowgentra_ai import SharedState, PlainState

# SharedState (thread-safe, default)
state = SharedState({"key": "value"})
state["name"] = "FlowgentraAI"
print(state["name"])        # "FlowgentraAI"
print("name" in state)      # True
print(state.to_dict())      # {"key": "value", "name": "FlowgentraAI"}
print(state.to_json())      # JSON string

# From/to JSON
state = SharedState.from_json('{"a": 1}')
state = SharedState.from_dict({"a": 1})
```

### Agent

```python
from flowgentra_ai import Agent, AgentConfig

# From config file
agent = Agent.from_config_path("config.yaml")

# From config object
config = AgentConfig.from_file("config.yaml")
agent = Agent.from_config(config)

# Run
result = agent.run()

# Run with thread (checkpointing)
result = agent.run_with_thread("thread-123")
```

### LLM Types

```python
from flowgentra_ai import LLMConfig, Message, TokenUsage

# LLM config
config = LLMConfig("openai", "gpt-4", api_key="sk-...")

# Messages
msg = Message.system("You are a helpful assistant")
msg = Message.user("What is Rust?")
msg = Message.assistant("Rust is a systems language")
msg = Message.tool("result", tool_call_id="call_123")

# Token usage & cost
usage = TokenUsage(1000, 500)
cost = usage.estimated_cost("gpt-4")
```

### RAG Utilities

```python
from flowgentra_ai import Document, chunk_text, extract_text, estimate_tokens

# Documents
doc = Document("doc-1", "Hello world", {"source": "example"})

# Text chunking
chunks = chunk_text("long text...", chunk_size=500, overlap=50)

# PDF extraction
text = extract_text("document.pdf")

# Token estimation
tokens = estimate_tokens("some text")
```

### Model Pricing

```python
from flowgentra_ai import model_pricing

pricing = model_pricing("gpt-4")  # (30.0, 60.0) per million tokens
```
