Metadata-Version: 2.4
Name: kagraphx
Version: 0.1.1
Summary: LangGraph-compatible agent orchestration with message-native state, checkpointing, and KaTrace Studio.
License-Expression: MIT
Project-URL: Homepage, https://github.com/anpc849/ka-graph
Project-URL: Repository, https://github.com/anpc849/ka-graph
Project-URL: Documentation, https://github.com/anpc849/ka-graph/tree/main/docs
Project-URL: Issues, https://github.com/anpc849/ka-graph/issues
Keywords: agents,llm,graph,langgraph,kaggle,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kaggle-benchmarks>=0.2.0
Requires-Dist: cloudpickle>=3.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: pillow>=10
Requires-Dist: ipython>=8
Requires-Dist: grandalf>=0.8
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# KaGraph

KaGraph is a LangGraph-compatible agent orchestration framework built on top of `kaggle_benchmarks` conversation primitives. It helps you build stateful, multi-node agent workflows with traceable execution, message-aware state updates, checkpointing, and a built-in web studio for inspecting graph behavior.

**If you find this project helpful and would like to support its development, consider buying me a coffee!**

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/huangan)

## Features

- **Native `kaggle_benchmarks` Integration**: Preserves message roles and objects directly without flattening context.
- **Stateful Workflows**: Define your state schema and update it incrementally through independent graph nodes.
- **Advanced Control Flow**: Supports conditional routing, fan-out/fan-in, timeouts, and retry policies.
- **Built-in Checkpointing**: Pause, inspect, and resume graph execution for human-in-the-loop workflows.
- **KaTrace Studio**: Visualize graph paths, inspect trace events, review LLM calls, compare messages, and replay past runs.

## Prerequisites

KaGraph relies on the `kaggle_benchmarks` library. In Kaggle notebooks, it is already available. In a local environment, install and configure it before running KaGraph.

For local development, configure your model proxy credentials:

```bash
cp .env.example .env
```

Then fill in `MODEL_PROXY_API_KEY` and `MODEL_PROXY_URL`.

## Installation

```bash
pip install kagraphx
```

For local development from source:

```bash
git clone https://github.com/anpc849/ka-graph.git
cd ka-graph
pip install -e ".[dev]"
```

## Quick Start

Start KaTrace Studio first so traces from your graph run are captured and visible:

```bash
# Local machine
kagraph-studio --mode local

# Kaggle notebook or remote environment
!kagraph-studio --mode localtunnel
```

Open `http://127.0.0.1:3000` in local mode, or use the printed LocalTunnel URL in tunnel mode.

Once Studio is running, execute a traced graph:

```python
from kagraph import START, END, StateGraph, MessagesState
from kagraph.llms import load_llm
from kagraph.prompts import invoke_llm
from kagraph.messages import HumanMessage
from kagraph.tracing import trace

llm = load_llm("qwen/qwen3-235b-a22b-instruct-2507")

def agent(state: MessagesState):
    response = invoke_llm(llm, messages=state["messages"], prompt="Answer the user.")
    return {"messages": [response]}

graph = StateGraph(MessagesState)
graph.add_node("agent", agent)
graph.add_edge(START, "agent")
graph.add_edge("agent", END)
app = graph.compile()

with trace("MyFirstAgent"):
    result = app.invoke({"messages": [HumanMessage("Hello!")]})

print(result["messages"][-1].content)
```

## Learn More

Use the docs for API details and the tutorial notebooks for runnable workflows:

- [Overview & Getting Started](docs/index.md)
- [Building Graphs (`StateGraph`)](docs/state_graph.md)
- [Running Graphs (`CompiledStateGraph`)](docs/compiled_graph.md)
- [Prebuilt Nodes & Utilities](docs/prebuilt.md)
- [KaTrace Studio & Tracing](docs/tracing.md)
- [Web Application Guide](docs/webapp/overview.md)
- [Tutorial notebooks](tutorials/)

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
