jaxforge 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (90) hide show
  1. jaxforge-0.2.0/.github/workflows/ci.yml +44 -0
  2. jaxforge-0.2.0/.github/workflows/docs.yml +55 -0
  3. jaxforge-0.2.0/.github/workflows/publish.yml +78 -0
  4. jaxforge-0.2.0/.gitignore +24 -0
  5. jaxforge-0.2.0/CHANGELOG.md +33 -0
  6. jaxforge-0.2.0/CONTRIBUTING.md +33 -0
  7. jaxforge-0.2.0/LICENSE +21 -0
  8. jaxforge-0.2.0/PKG-INFO +188 -0
  9. jaxforge-0.2.0/README.md +102 -0
  10. jaxforge-0.2.0/docs/api-reference.md +67 -0
  11. jaxforge-0.2.0/docs/architecture.md +32 -0
  12. jaxforge-0.2.0/docs/index.md +35 -0
  13. jaxforge-0.2.0/docs/quickstart.md +81 -0
  14. jaxforge-0.2.0/docs/security.md +30 -0
  15. jaxforge-0.2.0/docs/stylesheets/extra.css +118 -0
  16. jaxforge-0.2.0/examples/01_build_basic_mlp.py +18 -0
  17. jaxforge-0.2.0/examples/01_interactive_jax_gemini_basics.ipynb +76 -0
  18. jaxforge-0.2.0/examples/02_build_and_train_mnist.py +26 -0
  19. jaxforge-0.2.0/examples/02_end_to_end_mnist_pipeline.ipynb +94 -0
  20. jaxforge-0.2.0/examples/03_conversation_refinement.py +19 -0
  21. jaxforge-0.2.0/examples/04_save_and_load.py +22 -0
  22. jaxforge-0.2.0/examples/05_custom_training_loop.py +15 -0
  23. jaxforge-0.2.0/examples/06_data_pipeline.py +27 -0
  24. jaxforge-0.2.0/mkdocs.yml +43 -0
  25. jaxforge-0.2.0/pyproject.toml +92 -0
  26. jaxforge-0.2.0/src/jax_gemini/__init__.py +98 -0
  27. jaxforge-0.2.0/src/jax_gemini/agent.py +5 -0
  28. jaxforge-0.2.0/src/jax_gemini/config.py +5 -0
  29. jaxforge-0.2.0/src/jax_gemini/exceptions.py +23 -0
  30. jaxforge-0.2.0/src/jaxforge/__init__.py +80 -0
  31. jaxforge-0.2.0/src/jaxforge/agent.py +778 -0
  32. jaxforge-0.2.0/src/jaxforge/cli.py +112 -0
  33. jaxforge-0.2.0/src/jaxforge/codegen/__init__.py +15 -0
  34. jaxforge-0.2.0/src/jaxforge/codegen/diff.py +92 -0
  35. jaxforge-0.2.0/src/jaxforge/codegen/fixer.py +90 -0
  36. jaxforge-0.2.0/src/jaxforge/codegen/parser.py +58 -0
  37. jaxforge-0.2.0/src/jaxforge/codegen/validator.py +370 -0
  38. jaxforge-0.2.0/src/jaxforge/config.py +211 -0
  39. jaxforge-0.2.0/src/jaxforge/contrib/__init__.py +39 -0
  40. jaxforge-0.2.0/src/jaxforge/contrib/flax.py +49 -0
  41. jaxforge-0.2.0/src/jaxforge/contrib/optax.py +67 -0
  42. jaxforge-0.2.0/src/jaxforge/contrib/sharding.py +51 -0
  43. jaxforge-0.2.0/src/jaxforge/contrib/tracking.py +63 -0
  44. jaxforge-0.2.0/src/jaxforge/exceptions.py +60 -0
  45. jaxforge-0.2.0/src/jaxforge/exporter.py +63 -0
  46. jaxforge-0.2.0/src/jaxforge/llm/__init__.py +22 -0
  47. jaxforge-0.2.0/src/jaxforge/llm/base.py +35 -0
  48. jaxforge-0.2.0/src/jaxforge/llm/gemini.py +221 -0
  49. jaxforge-0.2.0/src/jaxforge/llm/providers.py +361 -0
  50. jaxforge-0.2.0/src/jaxforge/mcp_server.py +59 -0
  51. jaxforge-0.2.0/src/jaxforge/memory/__init__.py +5 -0
  52. jaxforge-0.2.0/src/jaxforge/memory/conversation.py +92 -0
  53. jaxforge-0.2.0/src/jaxforge/pipeline/__init__.py +13 -0
  54. jaxforge-0.2.0/src/jaxforge/pipeline/builder.py +19 -0
  55. jaxforge-0.2.0/src/jaxforge/pipeline/evaluator.py +16 -0
  56. jaxforge-0.2.0/src/jaxforge/pipeline/exporter.py +20 -0
  57. jaxforge-0.2.0/src/jaxforge/pipeline/trainer.py +21 -0
  58. jaxforge-0.2.0/src/jaxforge/plan.py +153 -0
  59. jaxforge-0.2.0/src/jaxforge/prompts/__init__.py +15 -0
  60. jaxforge-0.2.0/src/jaxforge/prompts/context_builder.py +142 -0
  61. jaxforge-0.2.0/src/jaxforge/prompts/intent.py +77 -0
  62. jaxforge-0.2.0/src/jaxforge/prompts/system_prompt.py +201 -0
  63. jaxforge-0.2.0/src/jaxforge/sandbox/__init__.py +25 -0
  64. jaxforge-0.2.0/src/jaxforge/sandbox/backends.py +385 -0
  65. jaxforge-0.2.0/src/jaxforge/sandbox/executor.py +80 -0
  66. jaxforge-0.2.0/src/jaxforge/sandbox/namespace.py +459 -0
  67. jaxforge-0.2.0/tests/__init__.py +1 -0
  68. jaxforge-0.2.0/tests/conftest.py +31 -0
  69. jaxforge-0.2.0/tests/integration/__init__.py +1 -0
  70. jaxforge-0.2.0/tests/integration/test_build_pipeline.py +42 -0
  71. jaxforge-0.2.0/tests/integration/test_full_conversation.py +37 -0
  72. jaxforge-0.2.0/tests/integration/test_train_pipeline.py +36 -0
  73. jaxforge-0.2.0/tests/unit/__init__.py +1 -0
  74. jaxforge-0.2.0/tests/unit/test_agent_and_namespace_coverage.py +161 -0
  75. jaxforge-0.2.0/tests/unit/test_backends_cli_mcp_contrib.py +122 -0
  76. jaxforge-0.2.0/tests/unit/test_checkpoint.py +73 -0
  77. jaxforge-0.2.0/tests/unit/test_config.py +61 -0
  78. jaxforge-0.2.0/tests/unit/test_context_builder.py +43 -0
  79. jaxforge-0.2.0/tests/unit/test_executor.py +221 -0
  80. jaxforge-0.2.0/tests/unit/test_gemini_llm.py +57 -0
  81. jaxforge-0.2.0/tests/unit/test_hygiene.py +55 -0
  82. jaxforge-0.2.0/tests/unit/test_intent.py +42 -0
  83. jaxforge-0.2.0/tests/unit/test_llm_lifecycle.py +128 -0
  84. jaxforge-0.2.0/tests/unit/test_memory.py +58 -0
  85. jaxforge-0.2.0/tests/unit/test_parser.py +30 -0
  86. jaxforge-0.2.0/tests/unit/test_pipeline_and_contrib.py +109 -0
  87. jaxforge-0.2.0/tests/unit/test_preview_explore_export.py +177 -0
  88. jaxforge-0.2.0/tests/unit/test_providers_and_routing.py +180 -0
  89. jaxforge-0.2.0/tests/unit/test_retry_security.py +113 -0
  90. jaxforge-0.2.0/tests/unit/test_validator.py +168 -0
@@ -0,0 +1,44 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, dev]
6
+ pull_request:
7
+ branches: [main, dev]
8
+
9
+ jobs:
10
+ lint-type-test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ fail-fast: false
14
+ matrix:
15
+ python-version: ["3.10", "3.11", "3.12"]
16
+
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+
20
+ - name: Set up Python ${{ matrix.python-version }}
21
+ uses: actions/setup-python@v5
22
+ with:
23
+ python-version: ${{ matrix.python-version }}
24
+
25
+ - name: Install dependencies
26
+ run: |
27
+ python -m pip install --upgrade pip
28
+ pip install -e ".[dev,viz,docs]"
29
+ pip check
30
+
31
+ - name: Lint with ruff
32
+ run: ruff check src tests examples
33
+
34
+ - name: Type-check with mypy
35
+ run: mypy src
36
+
37
+ - name: Run unit and integration tests with coverage
38
+ run: pytest --cov=jaxforge --cov-report=term-missing tests/
39
+
40
+ - name: Verify MkDocs documentation build
41
+ run: mkdocs build --strict
42
+
43
+ - name: Verify package build (sdist and wheel)
44
+ run: hatch build
@@ -0,0 +1,55 @@
1
+ name: Deploy Documentation
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+ pages: write
11
+ id-token: write
12
+
13
+ concurrency:
14
+ group: pages
15
+ cancel-in-progress: true
16
+
17
+ jobs:
18
+ build:
19
+ name: Build MkDocs site
20
+ runs-on: ubuntu-latest
21
+ steps:
22
+ - uses: actions/checkout@v4
23
+
24
+ - name: Set up Python 3.12
25
+ uses: actions/setup-python@v5
26
+ with:
27
+ python-version: "3.12"
28
+
29
+ - name: Install documentation dependencies
30
+ run: |
31
+ python -m pip install --upgrade pip
32
+ pip install -e ".[docs]"
33
+
34
+ - name: Build static site
35
+ run: mkdocs build --strict
36
+
37
+ - name: Configure GitHub Pages
38
+ uses: actions/configure-pages@v5
39
+
40
+ - name: Upload Pages artifact
41
+ uses: actions/upload-pages-artifact@v3
42
+ with:
43
+ path: site
44
+
45
+ deploy:
46
+ name: Deploy to GitHub Pages
47
+ needs: build
48
+ runs-on: ubuntu-latest
49
+ environment:
50
+ name: github-pages
51
+ url: ${{ steps.deployment.outputs.page_url }}
52
+ steps:
53
+ - name: Deploy to GitHub Pages
54
+ id: deployment
55
+ uses: actions/deploy-pages@v4
@@ -0,0 +1,78 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ build:
13
+ name: Build and verify distribution
14
+ runs-on: ubuntu-latest
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - name: Set up Python 3.12
19
+ uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.12"
22
+
23
+ - name: Verify release tag matches pyproject.toml version
24
+ if: github.event_name == 'release'
25
+ run: |
26
+ python - <<'EOF'
27
+ import os, tomllib
28
+ with open("pyproject.toml", "rb") as f:
29
+ pkg_version = tomllib.load(f)["project"]["version"]
30
+ tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
31
+ if tag != pkg_version:
32
+ raise SystemExit(
33
+ f"Release tag '{os.environ['GITHUB_REF_NAME']}' does not match "
34
+ f"pyproject.toml version '{pkg_version}'."
35
+ )
36
+ EOF
37
+
38
+ - name: Install dependencies and verification tools
39
+ run: |
40
+ python -m pip install --upgrade pip
41
+ pip install -e ".[dev,viz]" twine build
42
+
43
+ - name: Run lint, type check, and tests
44
+ run: |
45
+ ruff check src tests examples
46
+ mypy src
47
+ pytest --cov=jaxforge tests/
48
+
49
+ - name: Build sdist and wheel
50
+ run: |
51
+ rm -rf dist
52
+ python -m build
53
+ twine check dist/*
54
+
55
+ - name: Upload distribution artifacts
56
+ uses: actions/upload-artifact@v4
57
+ with:
58
+ name: release-dists
59
+ path: dist/
60
+
61
+ publish-pypi:
62
+ name: Publish package to PyPI
63
+ needs: build
64
+ runs-on: ubuntu-latest
65
+ environment:
66
+ name: pypi
67
+ url: https://pypi.org/p/jaxforge
68
+ permissions:
69
+ id-token: write
70
+ steps:
71
+ - name: Download distribution artifacts
72
+ uses: actions/download-artifact@v4
73
+ with:
74
+ name: release-dists
75
+ path: dist/
76
+
77
+ - name: Publish to PyPI via Trusted Publishing (OIDC)
78
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,24 @@
1
+ # Environment
2
+ venv/
3
+ venv_*/
4
+ env/
5
+ .env
6
+
7
+ # Build artifacts and caches
8
+ __pycache__/
9
+ *.py[cod]
10
+ *$py.class
11
+ .pytest_cache/
12
+ .ruff_cache/
13
+ .mypy_cache/
14
+ .coverage
15
+ htmlcov/
16
+ dist/
17
+ build/
18
+ *.egg-info/
19
+ .hatch/
20
+ site/
21
+ .DS_Store
22
+ # Application output
23
+ jax_gemini_checkpoints/
24
+ *.log
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ ## [0.2.0] - 2026-11-20
4
+
5
+ ### Added
6
+ - Rebranded core distribution to `jaxforge` (**Jax Forge**) with backward-compatible `jax_gemini` compatibility shims.
7
+ - Inspect-first workflow via `preview()`, `dry_run=True`, `approve=` callbacks, `GeneratedPlan` (including Jupyter HTML rendering and unified diffs), and incremental diff patching in `modify()`.
8
+ - Multi-provider LLM engine under `jaxforge.llm` supporting Google Gemini (`google-genai` SDK or HTTPS REST without deprecated `google-generativeai` warnings), OpenAI, Anthropic Claude, OpenRouter, LiteLLM, Ollama/vLLM local endpoints, primary/fast `RouterLLM`, and token/latency telemetry (`usage_summary()`).
9
+ - Pluggable sandbox `ExecutionBackend` implementations (`thread`, `subprocess` with `rlimit`, `docker`, `e2b`, `modal`).
10
+ - Privacy-preserving `DatasetProfile` injection, AIDE-inspired metric-guided `explore()`, `export_project()` standalone package export, async helpers (`abuild`, `atrain`, `aevaluate`, `apreview`), `jax.sharding` mesh/sharding utilities, `eval_shape_summary()`, cosine learning-rate schedules, experiment metric trackers, CLI (`jaxforge`), and MCP server (`jaxforge.mcp_server`).
11
+ - Support for optional Equinox modeling, Grain data loaders, and confined Safetensors weight loading.
12
+
13
+ ## [0.1.3] - 2026-11-20
14
+
15
+ ### Documentation and release engineering
16
+ - Applied strict editorial and typography standards across documentation, code messages, and prompt templates.
17
+ - Added MkDocs Material configuration (`mkdocs.yml`), token stylesheet (`docs/stylesheets/extra.css`), automated editorial hygiene tests, GitHub Pages deployment, and `publish.yml`.
18
+
19
+ ## [0.1.2] - 2026-11-20
20
+
21
+ ### Security and hardening
22
+ - Hardened `CodeValidator` AST checks, `_SafeModuleProxy` isolation, confined path resolution, non-swallowable sandbox timeouts, atomic config rollback, secret redaction, and bounded memory and prompt sizes.
23
+ - Added data pipeline intents, word-boundary `IntentClassifier`, `pipeline` and `contrib` modules, and GitHub Actions CI matrix.
24
+
25
+ ## [0.1.1] - 2026-04-22
26
+
27
+ ### Fixed
28
+ - Hatchling wheel package discovery configuration.
29
+
30
+ ## [0.1.0] - 2026-04-22
31
+
32
+ ### Added
33
+ - Initial `build()`, `train()`, AST validation, sandboxed execution, and conversation memory.
@@ -0,0 +1,33 @@
1
+ # Contributing guide
2
+
3
+ Contributions, bug reports, and documentation improvements to `jaxforge` (Jax Forge) are welcome.
4
+
5
+ ## Reporting issues
6
+
7
+ Open an issue on GitHub with reproduction steps, Python and JAX versions, configured provider/backend, and the relevant exception output.
8
+
9
+ ## Pull request workflow
10
+
11
+ 1. Branch from `main` using a descriptive branch name such as `fix/validator-edge-case` or `feat/provider-adapter`.
12
+ 2. Add or update unit and integration tests covering your change.
13
+ 3. Run linting, strict type checking, and the test suite with coverage before pushing.
14
+ 4. Open a pull request against `main` and link the corresponding issue.
15
+
16
+ ## Local development setup
17
+
18
+ Create a Python 3.10 to 3.12 virtual environment and install development extras:
19
+
20
+ ```bash
21
+ python -m venv venv
22
+ source venv/bin/activate
23
+ pip install -e ".[dev,viz,docs]"
24
+ ```
25
+
26
+ Run verification checks:
27
+
28
+ ```bash
29
+ ruff check src tests examples
30
+ mypy src
31
+ pytest --cov=jaxforge tests/
32
+ mkdocs build --strict
33
+ ```
jaxforge-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Wesley Kambale
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,188 @@
1
+ Metadata-Version: 2.5
2
+ Name: jaxforge
3
+ Version: 0.2.0
4
+ Summary: Model-agnostic natural language engineering workbench for JAX and Flax
5
+ Project-URL: Homepage, https://github.com/wkambale/jaxforge
6
+ Project-URL: Documentation, https://wkambale.github.io/jaxforge
7
+ Project-URL: Repository, https://github.com/wkambale/jaxforge
8
+ Project-URL: Issues, https://github.com/wkambale/jaxforge/issues
9
+ Project-URL: Changelog, https://github.com/wkambale/jaxforge/blob/main/CHANGELOG.md
10
+ Author-email: Wesley Kambale <spartanwk@gmail.com>
11
+ License: MIT License
12
+
13
+ Copyright (c) 2026 Wesley Kambale
14
+
15
+ Permission is hereby granted, free of charge, to any person obtaining a copy
16
+ of this software and associated documentation files (the "Software"), to deal
17
+ in the Software without restriction, including without limitation the rights
18
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
19
+ copies of the Software, and to permit persons to whom the Software is
20
+ furnished to do so, subject to the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be included in all
23
+ copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
26
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
27
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
28
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
29
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
30
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31
+ SOFTWARE.
32
+ License-File: LICENSE
33
+ Keywords: ai-agent,equinox,flax,jax,llm,machine-learning,neural-networks
34
+ Classifier: Intended Audience :: Developers
35
+ Classifier: Intended Audience :: Science/Research
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Programming Language :: Python :: 3.10
38
+ Classifier: Programming Language :: Python :: 3.11
39
+ Classifier: Programming Language :: Python :: 3.12
40
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
41
+ Requires-Python: >=3.10
42
+ Requires-Dist: flax>=0.9.0
43
+ Requires-Dist: jax>=0.4.25
44
+ Requires-Dist: numpy>=1.24.0
45
+ Requires-Dist: optax>=0.2.0
46
+ Requires-Dist: orbax-checkpoint>=0.6.0
47
+ Provides-Extra: anthropic
48
+ Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
49
+ Provides-Extra: dev
50
+ Requires-Dist: hatch; extra == 'dev'
51
+ Requires-Dist: mypy>=1.9.0; extra == 'dev'
52
+ Requires-Dist: pre-commit; extra == 'dev'
53
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
54
+ Requires-Dist: pytest>=8.0; extra == 'dev'
55
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
56
+ Provides-Extra: docker
57
+ Requires-Dist: docker>=7.0.0; extra == 'docker'
58
+ Provides-Extra: docs
59
+ Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
60
+ Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
61
+ Provides-Extra: e2b
62
+ Requires-Dist: e2b-code-interpreter>=1.0.0; extra == 'e2b'
63
+ Provides-Extra: equinox
64
+ Requires-Dist: equinox>=0.11.0; extra == 'equinox'
65
+ Provides-Extra: google
66
+ Requires-Dist: google-genai>=1.0.0; extra == 'google'
67
+ Provides-Extra: gpu
68
+ Requires-Dist: jax[cuda12]; extra == 'gpu'
69
+ Provides-Extra: grain
70
+ Requires-Dist: grain>=0.2.0; extra == 'grain'
71
+ Provides-Extra: litellm
72
+ Requires-Dist: litellm>=1.50.0; extra == 'litellm'
73
+ Provides-Extra: mcp
74
+ Requires-Dist: mcp>=1.0.0; extra == 'mcp'
75
+ Provides-Extra: modal
76
+ Requires-Dist: modal>=0.64.0; extra == 'modal'
77
+ Provides-Extra: openai
78
+ Requires-Dist: openai>=1.50.0; extra == 'openai'
79
+ Provides-Extra: safetensors
80
+ Requires-Dist: safetensors>=0.4.0; extra == 'safetensors'
81
+ Provides-Extra: tpu
82
+ Requires-Dist: jax[tpu]; extra == 'tpu'
83
+ Provides-Extra: viz
84
+ Requires-Dist: matplotlib>=3.8; extra == 'viz'
85
+ Description-Content-Type: text/markdown
86
+
87
+ <div align="center">
88
+ <h1>Jax Forge</h1>
89
+ <p><b>Model-agnostic natural language engineering workbench for JAX and Flax</b></p>
90
+
91
+ [![PyPI version](https://img.shields.io/pypi/v/jaxforge.svg)](https://pypi.org/project/jaxforge/0.2.0/)
92
+ [![Python Versions](https://img.shields.io/pypi/pyversions/jaxforge.svg)](https://pypi.org/project/jaxforge/0.2.0/)
93
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
94
+ [![CI](https://github.com/wkambale/jaxforge/actions/workflows/ci.yml/badge.svg)](https://github.com/wkambale/jaxforge/actions/workflows/ci.yml)
95
+ </div>
96
+
97
+ `jaxforge` (product name **Jax Forge**, formerly `jax-gemini`) enables machine learning engineers and researchers to preview, validate, build, train, explore, and export JAX and Flax workflows from natural language across any frontier or local LLM provider.
98
+
99
+ Unlike blind code-execution wrappers, `jaxforge` supports an inspect-first gate (`preview()`, `dry_run=True`, or `approve=` callbacks), privacy-preserving `DatasetProfile` summaries, unified diff edits, metric-guided tree-search exploration (`explore()`), isolated execution backends, and standalone Python package exports.
100
+
101
+ ## Core features
102
+
103
+ - **Inspect-first preview and approval**: Generate and AST-validate code with `jf.preview()` or `dry_run=True` to inspect source code, unified diffs, and shape estimates before running compute.
104
+ - **Multi-provider LLM routing**: Use Google Gemini, OpenAI, Anthropic Claude, OpenRouter, LiteLLM, or local Ollama and vLLM servers through `provider` or `model_name` prefixes (such as `anthropic:claude-sonnet-4-5`, `openai:gpt-5`, or `ollama:qwen2.5-coder:32b`) with fast/primary routing.
105
+ - **Production JAX workflows**: Supports Flax NNX and Equinox modeling, Optax schedules, `jax.sharding` device meshes, Grain streaming datasets, Orbax and Safetensors checkpoints, and `jax.eval_shape` checks.
106
+ - **Pluggable sandbox isolation**: Enforces AST allowlists, `WeakKeyDictionary` module proxies, and confined file I/O across `thread`, `subprocess` (with memory/CPU limits), `docker`, `e2b`, and `modal` backends.
107
+ - **Branching exploration and project export**: Compare candidate strategies with `jf.explore()` and materialize clean standalone Python packages via `jf.export_project()`, the `jaxforge` CLI, or the MCP server.
108
+
109
+ ## Quickstart
110
+
111
+ ### Installation
112
+
113
+ Install `jaxforge` from [PyPI](https://pypi.org/project/jaxforge/0.2.0/):
114
+
115
+ ```bash
116
+ pip install jaxforge
117
+ ```
118
+
119
+ Optional extras install provider SDKs, modeling frameworks, sandboxes, or plotting:
120
+
121
+ ```bash
122
+ pip install "jaxforge[google,openai,anthropic,viz]"
123
+ pip install "jaxforge[equinox,grain,safetensors]"
124
+ pip install "jaxforge[docker,e2b,modal,mcp]"
125
+ ```
126
+
127
+ Configure an API key for your chosen provider (or point `base_url` at a local Ollama or vLLM endpoint):
128
+
129
+ ```bash
130
+ export GEMINI_API_KEY="your-key" # or OPENAI_API_KEY / ANTHROPIC_API_KEY
131
+ ```
132
+
133
+ ### Preview, approve, train, and export
134
+
135
+ ```python
136
+ import jaxforge as jf
137
+ import numpy as np
138
+
139
+ # Switch providers freely: "gemini-3.1-pro", "openai:gpt-5", "anthropic:claude-sonnet-4-5", "ollama:llama3"
140
+ jf.config.set({"model_name": "anthropic:claude-sonnet-4-5"})
141
+
142
+ # Preview code and validation status before running anything
143
+ plan = jf.preview("Build a 4-layer MLP for 28x28 digit classification")
144
+ print(plan.code)
145
+
146
+ # Execute after review, or use build/modify/train with interactive approval
147
+ model = jf.build("Build a 4-layer MLP for digit classification")
148
+ model = jf.modify("Add dropout with rate 0.2 between hidden layers")
149
+
150
+ X_train = np.random.randn(100, 28, 28, 1).astype(np.float32)
151
+ y_train = np.random.randint(0, 10, size=(100,))
152
+
153
+ # Explore multiple candidate training runs against validation accuracy
154
+ experiment = jf.explore(
155
+ "Train classifier with cosine learning-rate decay",
156
+ dataset=(X_train, y_train),
157
+ metric="accuracy",
158
+ candidates=3,
159
+ )
160
+ print("Best accuracy:", experiment.best_candidate.score)
161
+
162
+ # Export generated modules into a standalone installable repository
163
+ jf.export_project("./exported_classifier", package_name="digit_classifier")
164
+ ```
165
+
166
+ ### CLI and MCP server
167
+
168
+ ```bash
169
+ jaxforge info
170
+ jaxforge devices
171
+ jaxforge preview "Build a Flax NNX residual classifier" --export ./out_pkg
172
+ jaxforge mcp
173
+ ```
174
+
175
+ See [examples/](examples/) for end-to-end Python scripts and notebooks.
176
+
177
+ ## Documentation
178
+
179
+ Full hosted documentation is published at [wkambale.github.io/jaxforge](https://wkambale.github.io/jaxforge):
180
+
181
+ - [Quickstart guide](docs/quickstart.md): Installation, provider configuration, preview gates, training, and project export.
182
+ - [API reference](docs/api-reference.md): Public functions, `GeneratedPlan`, execution backends, CLI, and contrib helpers.
183
+ - [Architecture internals](docs/architecture.md): Multi-provider routing, AST validation, sandbox backends, and memory.
184
+ - [Security protocol](docs/security.md): AST rules, import scoping, runtime proxies, path confinement, and timeout enforcement.
185
+
186
+ ## License and contributing
187
+
188
+ Read the [contribution guidelines](CONTRIBUTING.md) before opening issues or pull requests. Distributed under the MIT License; see [LICENSE](LICENSE) for full terms.
@@ -0,0 +1,102 @@
1
+ <div align="center">
2
+ <h1>Jax Forge</h1>
3
+ <p><b>Model-agnostic natural language engineering workbench for JAX and Flax</b></p>
4
+
5
+ [![PyPI version](https://img.shields.io/pypi/v/jaxforge.svg)](https://pypi.org/project/jaxforge/0.2.0/)
6
+ [![Python Versions](https://img.shields.io/pypi/pyversions/jaxforge.svg)](https://pypi.org/project/jaxforge/0.2.0/)
7
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
8
+ [![CI](https://github.com/wkambale/jaxforge/actions/workflows/ci.yml/badge.svg)](https://github.com/wkambale/jaxforge/actions/workflows/ci.yml)
9
+ </div>
10
+
11
+ `jaxforge` (product name **Jax Forge**, formerly `jax-gemini`) enables machine learning engineers and researchers to preview, validate, build, train, explore, and export JAX and Flax workflows from natural language across any frontier or local LLM provider.
12
+
13
+ Unlike blind code-execution wrappers, `jaxforge` supports an inspect-first gate (`preview()`, `dry_run=True`, or `approve=` callbacks), privacy-preserving `DatasetProfile` summaries, unified diff edits, metric-guided tree-search exploration (`explore()`), isolated execution backends, and standalone Python package exports.
14
+
15
+ ## Core features
16
+
17
+ - **Inspect-first preview and approval**: Generate and AST-validate code with `jf.preview()` or `dry_run=True` to inspect source code, unified diffs, and shape estimates before running compute.
18
+ - **Multi-provider LLM routing**: Use Google Gemini, OpenAI, Anthropic Claude, OpenRouter, LiteLLM, or local Ollama and vLLM servers through `provider` or `model_name` prefixes (such as `anthropic:claude-sonnet-4-5`, `openai:gpt-5`, or `ollama:qwen2.5-coder:32b`) with fast/primary routing.
19
+ - **Production JAX workflows**: Supports Flax NNX and Equinox modeling, Optax schedules, `jax.sharding` device meshes, Grain streaming datasets, Orbax and Safetensors checkpoints, and `jax.eval_shape` checks.
20
+ - **Pluggable sandbox isolation**: Enforces AST allowlists, `WeakKeyDictionary` module proxies, and confined file I/O across `thread`, `subprocess` (with memory/CPU limits), `docker`, `e2b`, and `modal` backends.
21
+ - **Branching exploration and project export**: Compare candidate strategies with `jf.explore()` and materialize clean standalone Python packages via `jf.export_project()`, the `jaxforge` CLI, or the MCP server.
22
+
23
+ ## Quickstart
24
+
25
+ ### Installation
26
+
27
+ Install `jaxforge` from [PyPI](https://pypi.org/project/jaxforge/0.2.0/):
28
+
29
+ ```bash
30
+ pip install jaxforge
31
+ ```
32
+
33
+ Optional extras install provider SDKs, modeling frameworks, sandboxes, or plotting:
34
+
35
+ ```bash
36
+ pip install "jaxforge[google,openai,anthropic,viz]"
37
+ pip install "jaxforge[equinox,grain,safetensors]"
38
+ pip install "jaxforge[docker,e2b,modal,mcp]"
39
+ ```
40
+
41
+ Configure an API key for your chosen provider (or point `base_url` at a local Ollama or vLLM endpoint):
42
+
43
+ ```bash
44
+ export GEMINI_API_KEY="your-key" # or OPENAI_API_KEY / ANTHROPIC_API_KEY
45
+ ```
46
+
47
+ ### Preview, approve, train, and export
48
+
49
+ ```python
50
+ import jaxforge as jf
51
+ import numpy as np
52
+
53
+ # Switch providers freely: "gemini-3.1-pro", "openai:gpt-5", "anthropic:claude-sonnet-4-5", "ollama:llama3"
54
+ jf.config.set({"model_name": "anthropic:claude-sonnet-4-5"})
55
+
56
+ # Preview code and validation status before running anything
57
+ plan = jf.preview("Build a 4-layer MLP for 28x28 digit classification")
58
+ print(plan.code)
59
+
60
+ # Execute after review, or use build/modify/train with interactive approval
61
+ model = jf.build("Build a 4-layer MLP for digit classification")
62
+ model = jf.modify("Add dropout with rate 0.2 between hidden layers")
63
+
64
+ X_train = np.random.randn(100, 28, 28, 1).astype(np.float32)
65
+ y_train = np.random.randint(0, 10, size=(100,))
66
+
67
+ # Explore multiple candidate training runs against validation accuracy
68
+ experiment = jf.explore(
69
+ "Train classifier with cosine learning-rate decay",
70
+ dataset=(X_train, y_train),
71
+ metric="accuracy",
72
+ candidates=3,
73
+ )
74
+ print("Best accuracy:", experiment.best_candidate.score)
75
+
76
+ # Export generated modules into a standalone installable repository
77
+ jf.export_project("./exported_classifier", package_name="digit_classifier")
78
+ ```
79
+
80
+ ### CLI and MCP server
81
+
82
+ ```bash
83
+ jaxforge info
84
+ jaxforge devices
85
+ jaxforge preview "Build a Flax NNX residual classifier" --export ./out_pkg
86
+ jaxforge mcp
87
+ ```
88
+
89
+ See [examples/](examples/) for end-to-end Python scripts and notebooks.
90
+
91
+ ## Documentation
92
+
93
+ Full hosted documentation is published at [wkambale.github.io/jaxforge](https://wkambale.github.io/jaxforge):
94
+
95
+ - [Quickstart guide](docs/quickstart.md): Installation, provider configuration, preview gates, training, and project export.
96
+ - [API reference](docs/api-reference.md): Public functions, `GeneratedPlan`, execution backends, CLI, and contrib helpers.
97
+ - [Architecture internals](docs/architecture.md): Multi-provider routing, AST validation, sandbox backends, and memory.
98
+ - [Security protocol](docs/security.md): AST rules, import scoping, runtime proxies, path confinement, and timeout enforcement.
99
+
100
+ ## License and contributing
101
+
102
+ Read the [contribution guidelines](CONTRIBUTING.md) before opening issues or pull requests. Distributed under the MIT License; see [LICENSE](LICENSE) for full terms.
@@ -0,0 +1,67 @@
1
+ # API reference
2
+
3
+ `jaxforge` exposes top-level session functions (`jf.preview`, `jf.build`, `jf.train`, `jf.explore`, `jf.export_project`) backed by a default `JaxForge` instance, plus the `JaxForge` class for isolated multi-session or server workflows. Backward-compatible `jax_gemini` imports emit a `DeprecationWarning` and alias directly to `JaxForge`.
4
+
5
+ ---
6
+
7
+ ### `jf.config.set(updates: dict) -> None`
8
+
9
+ Atomically validates and applies updates on `JaxForgeConfig`.
10
+
11
+ **Fields:**
12
+ - `provider` *(str)*: `"auto"`, `"google"`, `"openai"`, `"anthropic"`, `"ollama"`, `"openrouter"`, or `"litellm"` (Default: `"auto"`).
13
+ - `model_name` *(str)*: Target model or `provider:model` prefix spec (Default: `"gemini-3.1-pro"`).
14
+ - `fast_model_name` *(str | None)*: Optional faster model used for retry repairs (Default: `None`).
15
+ - `api_key` / `gemini_api_key` *(str | None)*: API key (reads matching env var when unset).
16
+ - `base_url` *(str | None)*: Optional HTTP(S) base URL for Ollama, vLLM, or custom proxies.
17
+ - `framework` *(str)*: `"flax"`, `"equinox"`, or `"auto"` (Default: `"flax"`).
18
+ - `execution_backend` *(str)*: `"thread"`, `"subprocess"`, `"docker"`, `"e2b"`, or `"modal"` (Default: `"thread"`).
19
+ - `max_memory_mb` *(int | None)*: Memory limit for `subprocess` and `docker` backends (Default: `None`).
20
+ - `auto_approve` *(bool)*: Require explicit `approve=` callback when `False` (Default: `True`).
21
+ - `temperature` *(float)*: Sampling temperature in `[0.0, 1.0]` (Default: `0.2`).
22
+ - `max_output_tokens` *(int)*: Maximum output tokens in `[1, 65536]` (Default: `4096`).
23
+ - `max_retries` *(int)*: Generation retry attempts in `[1, 5]` (Default: `3`).
24
+ - `timeout_seconds` *(int)*: Request and sandbox timeout in `[1, 3600]` (Default: `60`).
25
+ - `checkpoint_dir` *(str)*: Confined base directory for checkpoints (Default: `"./jaxforge_checkpoints"`).
26
+ - `verbose` *(bool)*: Print execution logs (Default: `False`).
27
+
28
+ ---
29
+
30
+ ### `jf.preview(prompt: str, intent: str | None = None, dataset: Any = None, diff_mode: bool = False) -> GeneratedPlan`
31
+
32
+ Generates and AST-validates code without executing it, returning a `GeneratedPlan` with optional unified diffs and Jupyter HTML rendering. Use `agent.execute_plan(plan, ...)` to execute after approval.
33
+
34
+ ---
35
+
36
+ ### `jf.build` / `jf.modify` / `jf.train` / `jf.evaluate` / `jf.run`
37
+
38
+ All primary execution methods accept `dry_run: bool = False` and `approve: Callable[[GeneratedPlan], bool] | None = None` for inspect-first gates, and async variants `abuild`, `amodify`, `atrain`, `aevaluate`, and `apreview` on `JaxForge`.
39
+
40
+ ---
41
+
42
+ ### `jf.explore(prompt: str, dataset: Any, metric: str = "accuracy", maximize: bool = True, candidates: int = 3) -> ExperimentResult`
43
+
44
+ Runs bounded branching trials across optimization strategies and promotes the highest-scoring candidate model.
45
+
46
+ ---
47
+
48
+ ### `jf.export_project(output_dir: str | Path, package_name: str = "generated_model") -> Path`
49
+
50
+ Writes generated `model.py`, optional `train.py` and `eval.py`, `pyproject.toml`, and `tests/test_smoke.py` into `output_dir`.
51
+
52
+ ---
53
+
54
+ ### Data pipeline, checkpoints, telemetry, and inspection
55
+
56
+ - `jf.save(name)` and `jf.load(name)`: Confined Orbax/Safetensors persistence inside `checkpoint_dir`.
57
+ - `jf.load_data()`, `jf.preprocess_data()`, `jf.analyze_data()`, `jf.visualize_data()`: Confined dataset operations profiled automatically by `DatasetProfile`.
58
+ - `jf.explain()`, `jf.show_code()`, `jf.usage_summary()`, `jf.reset()`: Inspection, token/latency accounting, and session reset.
59
+
60
+ ---
61
+
62
+ ### CLI, MCP, pipeline, and contrib helpers
63
+
64
+ - CLI entrypoint: `jaxforge {info,devices,validate,preview,run,mcp}`.
65
+ - `jaxforge.mcp_server`: `tool_validate_jax_code`, `tool_device_summary`, `tool_run_sandboxed_jax`, and `serve_stdio()`.
66
+ - `jaxforge.pipeline`: `ModelBuilder`, `ModelTrainer`, `ModelEvaluator`, `ModelExporter`.
67
+ - `jaxforge.contrib`: `count_parameters`, `summarize_module`, `eval_shape_summary`, `available_optimizers`, `create_optimizer`, `create_cosine_schedule`, `count_opt_steps`, `device_summary`, `create_device_mesh`, `make_replicated_sharding`, `make_data_sharding`, `InMemoryTracker`, `JsonlTracker`, `create_tracker`.