nodex-ai 0.1.0__tar.gz

nodex_ai-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Report something broken or confusing
+title: "bug: "
+labels: bug
+assignees: ""
+---
+
+## What happened?
+
+Describe the bug clearly.
+
+## Reproduction
+
+Steps or a minimal code sample:
+
+```python
+from nodex import Agent
+```
+
+## Expected behavior
+
+What did you expect Nodex to do?
+
+## Environment
+
+- Python version:
+- Nodex version or commit:
+- Operating system:
+- LangGraph version:
+
+## Logs or output
+
+Paste relevant terminal output here.

nodex_ai-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest a new capability or improvement
+title: "feature: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What pain point should this solve?
+
+## Proposed solution
+
+Describe the API or behavior you want.
+
+## Example
+
+```python
+from nodex import Agent
+```
+
+## Alternatives considered
+
+What other approaches did you think about?
+
+## Extra context
+
+Add screenshots, links, or related issues if useful.

nodex_ai-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,37 @@
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload site
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

nodex_ai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nodex_ai-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest

nodex_ai-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+.installed.cfg
+lib/
+lib64/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# nodex specific
+*.trace
+*.nodex_cache

nodex_ai-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

nodex_ai-0.1.0/.python-version

@@ -0,0 +1,2 @@
+3.11
+

nodex_ai-0.1.0/AGENTS.md

@@ -0,0 +1,28 @@
+# Agent Contribution Guide
+
+This file is for AI coding agents working on Nodex.
+
+## Rules
+
+- Read the relevant source files before editing.
+- Keep `src/nodex` behavior aligned with `README.md`, `docs/`, and `site/`.
+- Use ASCII-safe terminal output unless there is a tested reason not to.
+- Do not introduce provider-specific dependencies into the core package.
+- Add or update tests for behavior changes.
+- Run `ruff check src tests` and `pytest` before handing off.
+
+## Important behavior
+
+- `Agent.run()` returns an `ExecutionTrace`.
+- Node functions must return a non-empty dictionary.
+- `next="end"` finishes the graph.
+- Middleware wraps node execution in registration order.
+- Route metadata should work in both decorator orders.
+- Testing helpers are public through `nodex.testing`.
+
+## Do not
+
+- Revert user work without explicit instruction.
+- Replace LangGraph internals with a custom graph engine.
+- Document features that do not exist.
+- Add large framework dependencies to the docs site without asking.

nodex_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for helping improve Nodex.
+
+## Local setup
+
+```bash
+git clone https://github.com/VamsiKrishna0101/nodex
+cd nodex
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+On macOS or Linux:
+
+```bash
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Checks
+
+Run these before opening a pull request:
+
+```bash
+ruff check src tests
+pytest
+```
+
+## Development guidelines
+
+- Keep the public API small and obvious.
+- Prefer examples that run without extra infrastructure.
+- Do not document behavior that is not covered by tests.
+- Keep terminal output ASCII-safe so Windows users do not hit encoding issues.
+- Add tests for user-facing behavior, especially CLI and graph execution paths.
+
+## Pull requests
+
+Include:
+
+- what changed,
+- why it changed,
+- tests added or updated,
+- and any behavior users should know about.

nodex_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vamsi Krishna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodex_ai-0.1.0/Makefile

@@ -0,0 +1,11 @@
+test:
+	pytest
+
+lint:
+	ruff check src tests examples
+
+format:
+	ruff format src tests examples
+
+publish:
+	hatch build

nodex_ai-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: nodex-ai
+Version: 0.1.0
+Summary: The Express.js-style developer experience for LangGraph agents.
+Project-URL: Homepage, https://github.com/VamsiKrishna0101/Nodex
+Project-URL: Documentation, https://vamsikrishna0101.github.io/Nodex/
+Project-URL: Repository, https://github.com/VamsiKrishna0101/Nodex
+Project-URL: Bug Tracker, https://github.com/VamsiKrishna0101/Nodex/issues
+Project-URL: Changelog, https://github.com/VamsiKrishna0101/Nodex/releases
+Author-email: Vamsi Krishna <vklvl0101@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Vamsi Krishna
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agentic-ai,agents,ai,framework,langchain,langgraph,llm,multi-agent,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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.11
+Requires-Dist: langchain-core>=0.2.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: watchfiles>=0.21.0
+Provides-Extra: dev
+Requires-Dist: hatch>=1.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# nodex
+
+**The Express.js-style developer experience for LangGraph agents.**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/VamsiKrishna0101/Nodex/actions/workflows/test.yml/badge.svg)](https://github.com/VamsiKrishna0101/Nodex/actions)
+
+Nodex is a thin layer on top of LangGraph that lets you build agents with
+decorators, middleware, retries, fallbacks, tracing, and a small CLI.
+
+It does not replace LangGraph. It removes the boilerplate around it.
+
+## Why
+
+LangGraph is powerful, but even a small agent can require manual state types,
+node registration, edge wiring, retry handling, and debugging through several
+layers of framework internals.
+
+Nodex gives that workflow a smaller surface:
+
+- Define graph steps with `@app.node`.
+- Add cross-cutting behavior with `@app.middleware`.
+- Route conditionally with `@app.route`.
+- Run the graph with `app.run(...)`.
+- Get a terminal execution trace automatically.
+
+## Install
+
+```bash
+pip install nodex-ai
+```
+
+Requires Python 3.11 or newer.
+
+## Quickstart
+
+```python
+from nodex import Agent
+
+app = Agent(name="hello-agent")
+
+
+@app.node(next="writer")
+def research(state):
+    query = state.get("query", "LangGraph")
+    return {"notes": f"Research notes about {query}"}
+
+
+@app.node(next="end")
+def writer(state):
+    return {"final": state.get("notes").upper()}
+
+
+if __name__ == "__main__":
+    app.run({"query": "agent frameworks"})
+```
+
+Output:
+
+```text
+>  nodex running - hello-agent
+--------------------------------------------------
+OK  research       ->  0.002s  |  tokens: 0  |  $0.0000
+OK  writer         ->  0.001s  |  tokens: 0  |  $0.0000
+--------------------------------------------------
+OK  Completed  |  0.023s  |  $0.0000  |  2 nodes  |  0 failed  |  tokens: 0
+```
+
+## LangGraph vs Nodex
+
+LangGraph:
+
+```python
+from langgraph.graph import END, START, StateGraph
+
+graph = StateGraph(dict)
+graph.add_node("research", research)
+graph.add_node("writer", writer)
+graph.add_edge(START, "research")
+graph.add_edge("research", "writer")
+graph.add_edge("writer", END)
+app = graph.compile()
+```
+
+Nodex:
+
+```python
+from nodex import Agent
+
+app = Agent()
+
+
+@app.node(next="writer")
+def research(state):
+    return {"notes": "research"}
+
+
+@app.node(next="end")
+def writer(state):
+    return {"final": state.get("notes")}
+
+
+app.run()
+```
+
+## Core API
+
+### Agent
+
+```python
+from nodex import Agent
+
+app = Agent(name="research-agent", debug=True)
+```
+
+`Agent` owns node registration, middleware registration, graph compilation, and
+execution tracing.
+
+### Nodes
+
+```python
+@app.node(next="writer", retry=2, on_fail="fallback_research")
+def research(state):
+    return {"research_results": "data"}
+```
+
+Node functions receive a `NodexState` object and must return a non-empty
+dictionary. Internal keys such as `_trace` and `_retry_count` are protected.
+
+### Middleware
+
+```python
+@app.middleware
+def logger(state, next_node):
+    print(f"running {state._current_node}")
+    return next_node(state)
+```
+
+Middleware runs in registration order and wraps node execution.
+
+### Conditional routing
+
+```python
+@app.node()
+@app.route(
+    condition=lambda state: state.get("confidence", 0) > 0.8,
+    if_true="publish",
+    if_false="review",
+)
+def writer(state):
+    return {"draft": "ready"}
+```
+
+### Human review
+
+```python
+@app.node(next="publish", human_review=True)
+def review(state):
+    return {"approved_content": state.get("draft")}
+```
+
+When `human_review=True`, Nodex asks for terminal approval before continuing.
+
+## CLI
+
+```bash
+nodex new my-agent
+cd my-agent
+nodex dev agent:app
+nodex run agent:app --input '{"query":"hello"}'
+```
+
+## Testing nodes
+
+```python
+from nodex.testing import assert_node_output, test_node
+
+
+def test_research():
+    result = test_node(research, {"query": "AI trends"})
+    assert result.success
+    assert "research_results" in result.output
+
+
+def test_required_keys():
+    assert_node_output(research, {"query": "AI trends"}, ["research_results"])
+```
+
+## Local development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests
+pytest
+```
+
+Current test suite: 58 tests, with app, graph, CLI, decorators, middleware,
+state, tracer, errors, and testing helpers covered.
+
+## Documentation
+
+The local docs site lives in `site/` and can be served with:
+
+```bash
+npm run dev
+```
+
+Then open `http://127.0.0.1:4173/`.
+
+## Roadmap
+
+- Decorator-based node definition
+- Middleware engine
+- Retry and fallback handling
+- Terminal execution tracing
+- CLI scaffold/run/dev commands
+- Testing helpers
+- Multi-page docs site
+- Provider-specific examples
+- Dashboard or trace viewer
+
+## License
+
+MIT. See [LICENSE](LICENSE).