Metadata-Version: 2.4
Name: graphon
Version: 0.4.0
Summary: Graph execution engine for agentic AI workflows.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: charset-normalizer>=2.1
Requires-Dist: httpx>=0.28
Requires-Dist: json-repair>=0.55
Requires-Dist: jsonschema>=4
Requires-Dist: orjson>=3
Requires-Dist: pandas[excel]>=2.1
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-extra-types>=2
Requires-Dist: pypdfium2>=5
Requires-Dist: python-docx>=1.2
Requires-Dist: pyyaml>=6
Requires-Dist: tiktoken>=0.12
Requires-Dist: transformers>=4
Requires-Dist: typing-extensions>=4.10.0
Requires-Dist: unstructured[docx,epub,md,ppt,pptx]>=0.21
Requires-Dist: pypandoc>=1.13
Requires-Dist: webvtt-py>=0.5
Requires-Python: >=3.12, <3.14
Project-URL: source, https://github.com/langgenius/graphon
Project-URL: homepage, https://github.com/langgenius/graphon
Project-URL: issues, https://github.com/langgenius/graphon/issues
Description-Content-Type: text/markdown

# Graphon

Graphon is a Python graph execution engine for agentic AI workflows.

The repository is still evolving, but it already contains a working execution
engine, built-in workflow nodes, model runtime abstractions, integration
protocols, and a runnable end-to-end example.

## Highlights

- Queue-based `GraphEngine` orchestration with event-driven execution
- Graph parsing, validation, and fluent graph building
- Shared runtime state, variable pool, and workflow execution domain models
- Built-in node implementations for common workflow patterns
- DSL import support with Slim-backed LLM nodes
- HTTP, file, tool, and human-input integration protocols
- Extensible engine layers and external command channels

Repository modules currently cover node types such as `start`, `end`, `answer`,
`llm`, `if-else`, `code`, `template-transform`, `question-classifier`,
`http-request`, `tool`, `variable-aggregator`, `variable-assigner`, `loop`,
`iteration`, `parameter-extractor`, `document-extractor`, `list-operator`, and
`human-input`.

## Quick Start

Graphon is currently easiest to evaluate from a source checkout.

### Requirements

- Python 3.12 or 3.13
- [`uv`](https://docs.astral.sh/uv/)
- `make`

Python 3.14 is currently unsupported because `unstructured`, which backs part
of the document extraction stack, currently declares `Requires-Python: <3.14`.

### Set up the repository

```bash
make dev
source .venv/bin/activate
make test
```

`make dev` installs the project, syncs development dependencies, and sets up
[`prek`](https://prek.j178.dev/) Git hooks. `make test` is the progressive
local validation entrypoint: it formats, applies lint fixes, runs `ty check`,
and then runs `pytest`.

## Run the Example Workflows

The repository includes minimal runnable Slim LLM examples at
[`examples/slim_llm`](examples/slim_llm).

Both versions execute this workflow:

```text
start -> llm -> answer
```

To run it:

```bash
make dev
source .venv/bin/activate
cd examples/slim_llm
cp credentials.example.json credentials.json
python3 dsl.py "Reply with only the word Graphon."
python3 code.py "Reply with only the word Graphon."
```

Before running the example, fill in the required values in `credentials.json`.

The example currently expects:

- OpenAI-compatible model credentials in `model_credentials`
- `slim.mode` set to either `local` or `remote`
- `dify-plugin-daemon-slim` in `PATH`, `SLIM_BINARY_PATH`, or a local `slim`
  binary in the example directory
- for remote mode, `daemon_addr` and `daemon_key`

For the exact credential shape and runtime notes, see
[examples/slim_llm/README.md](examples/slim_llm/README.md).

## How Graphon Fits Together

At a high level, direct Graphon usage looks like this:

1. Build or load a graph and instantiate nodes into a `Graph`.
2. Prepare `GraphRuntimeState` and seed the `VariablePool`.
3. Configure model, file, HTTP, tool, or human-input adapters as needed.
4. Run `GraphEngine` and consume emitted graph events.
5. Read final outputs from runtime state.

For Dify DSL documents, use `graphon.dsl.loads()` to build the engine from the
workflow YAML and credentials. The resulting engine uses the DSL Slim adapter
for LLM nodes:

```python
engine = loads(
    dsl,
    credentials=credentials,
    workflow_id="example-dsl-openai-slim",
    start_inputs={"query": query},
)

events = list(engine.run())
```

See [examples/slim_llm/dsl.py](examples/slim_llm/dsl.py) for the DSL import
version and [examples/slim_llm/code.py](examples/slim_llm/code.py) for the
Python graph construction version.

For direct Python graph construction, use `graphon.dsl.slim.SlimLLM` as the
standard Slim-backed LLM runtime. Integrations that need to replace model
execution, routing, credential injection, or token counting can implement
`graphon.protocols.LLMProtocol`. A higher-level model factory/resolver layer is
planned as a separate follow-up.

## Project Layout

- `src/graphon/graph`: graph structures, parsing, validation, and builders
- `src/graphon/graph_engine`: orchestration, workers, command channels, and
  layers
- `src/graphon/runtime`: runtime state, read-only wrappers, and variable pool
- `src/graphon/nodes`: built-in workflow node implementations
- `src/graphon/model_runtime`: provider/model abstractions and shared model
  entities
- `src/graphon/dsl`: DSL import support, including Slim-backed runtime adapters
- `src/graphon/graph_events`: event models emitted during execution
- `src/graphon/http`: HTTP client abstractions and default implementation
- `src/graphon/file`: workflow file models and file runtime helpers
- `src/graphon/protocols`: public protocol re-exports for integrations
- `examples/`: runnable examples
- `tests/`: unit and integration-style coverage

## Internal Docs

- [CONTRIBUTING.md](CONTRIBUTING.md): contributor workflow, CI, commit/PR rules
- [examples/slim_llm/README.md](examples/slim_llm/README.md):
  runnable Slim LLM example setup
- [src/graphon/model_runtime/README.md](src/graphon/model_runtime/README.md):
  model runtime overview
- [src/graphon/graph_engine/layers/README.md](src/graphon/graph_engine/layers/README.md):
  engine layer extension points
- [src/graphon/graph_engine/command_channels/README.md](src/graphon/graph_engine/command_channels/README.md):
  local and distributed command channels

## Development

Contributor setup, tooling details, CLA notes, and commit/PR conventions live
in [CONTRIBUTING.md](CONTRIBUTING.md).

CI currently validates pull request titles, runs `make check` including
`uv.lock` freshness validation, and runs `uv run pytest` on Python 3.12 and
3.13. Python 3.14 is currently excluded because `unstructured` does not yet
support it.

## License

Apache-2.0. See [LICENSE](LICENSE).
