{"id":37683164,"url":"https://github.com/mdrideout/junjo","last_synced_at":"2026-01-16T12:28:19.048Z","repository":{"id":292705205,"uuid":"929918337","full_name":"mdrideout/junjo","owner":"mdrideout","description":"An AI graph workflow library for building dynamic LLM driven workflows","archived":false,"fork":false,"pushed_at":"2025-11-22T23:46:45.000Z","size":2603,"stargazers_count":18,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-23T00:15:54.016Z","etag":null,"topics":["agents","ai","ai-workflows","dag","directed-graph","llm","workflow"],"latest_commit_sha":null,"homepage":"https://python-api.junjo.ai/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mdrideout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-02-09T17:45:25.000Z","updated_at":"2025-10-12T17:28:24.000Z","dependencies_parsed_at":"2025-09-12T21:08:00.297Z","dependency_job_id":"9aac15a5-5f4d-4442-83fc-540e70318894","html_url":"https://github.com/mdrideout/junjo","commit_stats":null,"previous_names":["mdrideout/junjo"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/mdrideout/junjo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdrideout%2Fjunjo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdrideout%2Fjunjo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdrideout%2Fjunjo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdrideout%2Fjunjo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdrideout","download_url":"https://codeload.github.com/mdrideout/junjo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdrideout%2Fjunjo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478650,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","ai-workflows","dag","directed-graph","llm","workflow"],"created_at":"2026-01-16T12:28:18.933Z","updated_at":"2026-01-16T12:28:19.037Z","avatar_url":"https://github.com/mdrideout.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Junjo 順序\n\n\u003e Japanese Translation: order, sequence, procedure\n\nJunjo is a modern Python library for designing, executing, testing, and debugging complex, graph-based AI workflows.\n\nWhether you’re building a simple chatbot, a complex data manipulation pipeline, or a sophisticated workflow with dynamic branching and parallel execution, Junjo provides the tools to define your logic as a clear graph of nodes and edges.\n\n#### Docs\n\n- [Python API Docs](https://python-api.junjo.ai/)\n- [PyPI](https://pypi.org/project/junjo/)\n\n#### Benefits:\n\n- Asyncio \u0026 Pydantic native\n- Visualize your AI workflows\n- Build in redux-inspired state machine\n- Create robust and predictable conditional chains of LLM calls\n- Organize complex workflow executions into a scalable clean Graph structure\n- Manage execution order, loops, and concurrency\n- Supports Eval-Driven Development techniques\n  - Test every node of your workflow to 100% evaluation accuracy\n  - Test your workflows with dozens or thousands of input cases\n  - Rapidly iterate on your AI capabilities knowing for sure you're making progress\n- Native opentelemetry support for clear tracing, observability, and debugging\n  - Try our **optional, free, open source** companion [junjo-server](https://github.com/mdrideout/junjo-server) telemetry server.\n\n\u003cimg src=\"https://raw.githubusercontent.com/mdrideout/junjo/main/junjo-screenshot.png\" width=\"600\" /\u003e\n\n_junjo-screenshot.png_\n\n#### Decoupled\n\nJunjo doesn't change how you create AI / LLM calls. Use any AI or LLM service provider or library. Junjo simply helps you organize your python functions into a clean organized graph structure with predictable, testable execution.\n\nJunjo provides the building blocks that let you make any sort of executable workflow. From linear function calls, to complex branching workflows with concurrent sublfows, to fully autonomous agents.\n\n\u003e \n\u003e There are zero proprietary AI / LLM implementations in Junjo. Use whatever LLM library you want.\n\u003e \n\u003e All logs produced are opentelemetry compatible. Existing otel spans are annotated with workflow and node execution span wrappers.\n\u003e \n\nIt doesn't matter if the functions you add to a Junjo workflow are LLM API calls, database operations, or traditional business logic. You can write your business logic however you want. We just provide a convenient framework for organizing your desired flow into an executable graph.\n\n### Building AI Workflows and Agents as a Graph Workflow\n\nAgentic AI applications use LLMs to determine the order of execution of python functions. These functions may involve LLM requests, API requests, database CRUD operations, etc.\n\nThe simplest way to organize functions that can be / need to be executed in a certain order is in the form of a [directed graph](https://en.wikipedia.org/wiki/Directed_graph).\n\nA directed graph gives one the building blocks to create any sort of agentic application, including:\n\n- High precision workflows in the form of a Directed Acyclic Graph (DAG)\n- Autonomous AI Agents in the form of dynamically determined directed graphs\n\n### Priorities\n\nTest (eval) driven development, repeatability, debuggability, and telemetry are **CRITICAL** for rapid iteration and development of Agentic applications.\n\nJunjo prioritizes the following capabilities above all else to ensure these things are not an afterthought. \n\n1. Eval driven development / Test driven development with pytest\n1. Telemetry\n1. Visualization\n1. Type safety (pydantic)\n1. Concurrency safe (asyncio)\n\n\n## Contributing\n\nThis project was made with the [uv](https://github.com/astral-sh/uv) python package manager.\n\n```bash\n# Setup and activate the virtual environment\n$ uv venv .venv\n$ source .venv/bin/activate\n\n# Install optional development dependencies (graphviz is optional for running the graphviz visualizer)\n# Graphviz, if utilized, must also be installed on the host system (see below)\n$ uv pip install -e \".[dev,graphviz]\"\n```\n\n## Visualizing Your Workflows\n\n### Junjo Server\n\n[Junjo Server](https://github.com/mdrideout/junjo-server) is an optional, free, open-source companion telemetry visualization platform for debugging Junjo workflows.\n\n**Quick Start:**\n\n```bash\n# Create docker-compose.yml (see docs for full example)\n# Start services\ndocker compose up -d\n\n# Access UI at http://localhost:5153\n```\n\n**Features:**\n- Interactive graph visualization with execution path tracking\n- State step debugging - see every state change in chronological order\n- LLM decision tracking and trace timeline\n- Multi-execution comparison\n- Built specifically for graph-based AI workflows\n\n**Architecture:** Three-service Docker setup (backend, ingestion service, frontend) that runs on minimal resources (1GB RAM, shared vCPU).\n\nSee the [Junjo Server documentation](https://python-api.junjo.ai/junjo_server.html) for complete setup and configuration.\n\n### Graphviz\n\nJunjo can render workflow graphs as images. It requires [Graphviz](https://graphviz.org/) to be installed on the underlying system (your developer computer or the docker image), as well as the above optional graphviz development dependencies in this python library.\n\n```bash\n# Install Graphviz on MacOS with homebrew\n$ brew install graphviz\n```\n\n```python\n# visualize.py\nfrom base.sample_workflow.graph import create_sample_workflow_graph\n\ndef main():\n    # Every graph can execute .export_graphviz_assets() to generate all graphs and subflow graphs in a workflow\n    # Creates .svg renderings, .dot notation files, and an HTML template to render the graphs\n    create_sample_workflow_graph().export_graphviz_assets()\n\nif __name__ == \"__main__\":\n    main()\n```\n\n```bash\n# Run the visualizer\npython -m src.base.visualize\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/mdrideout/junjo/main/junjo-screenshot-graphviz.png\" width=\"600\" /\u003e\n\n#### Full Example\n**See the full example inside `examples/base`.**\n\n## Contributing\n\n### Code Linting and Formatting\n\nThis project utilizes [ruff](https://astral.sh/ruff) for linting and auto formatting. The VSCode settings.json in this project helps with additional formatting.\n\n- [Ruff VSCode Extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)\n\n### Building The Sphinx Docs\n\n```bash\n# 1. ensure optional development dependencies are installed (see above)\n# 2. ensure the virtual environment is activated (see above)\n\n# Execute the build command to preview the new docs.\n# They will appear in a .gitignored folder docs/_build\n$ sphinx-build -b html docs docs/_build\n```\n\n### Tests\n\n```bash\n# Run the tests with uv\n$ uv run pytest\n```\n\n## Code Generation\n\n### Protobuf schema generation\n\n1. Requires the optional `dev` dependencies to be installed via `uv pip install -e \".[dev]\"`\n2. Requires [protoc](https://grpc.io/docs/protoc-installation/) which can be installed into your developer environment host machine ([instructions](https://grpc.io/docs/protoc-installation/)).\n3. Copy the .proto files from the junjo-server project to `src/telemetry/junjo_server/proto`\n4. Run `make proto` from the project root to generate the `proto_gen` files for the client\n5. Update any required changes to the `src/telemetry/junjo_server/client.py` file (type changes, fields, etc.)\n\n### Pre-commit Hook\n\nThis project uses a pre-commit hook to automatically generate the protobuf files. To install the hook, run the following command:\n\n```bash\npre-commit install\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdrideout%2Fjunjo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdrideout%2Fjunjo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdrideout%2Fjunjo/lists"}