silver-lang 0.1.0__tar.gz

silver_lang-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable Silver changes should be recorded here.
+
+## 0.1.0
+
+- Added the native `silver-lang` npm package for Node.js 18 and newer.
+- Added TypeScript declarations, ESM exports, and the `silver` CLI.
+- Added native language execution, deterministic traces, compiler, bytecode,
+  stack VM, runtime memory utilities, graph models, package management, agent
+  workflows, application planning, module loading, and IDE models.
+- Added native ML layers, classifiers, tensor inspection, autodiff, and ML source
+  compilation.
+- Added computed neural-network inspection, Silver/Python teaching translation,
+  deterministic TinyGPT generation, virtual large-model profiles, and typed
+  blueprints for Transformer and deep-learning model families.
+- Documented the executable reference path separately from architecture
+  blueprints and added a clearer contributor and local tarball workflow.
+- Added local tarball testing instructions so consumers can validate a release
+  before registry publication.

silver_lang-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code of Conduct
+
+Silver contributors are expected to make participation respectful, practical,
+and accessible to people with different backgrounds and levels of experience.
+
+Unacceptable behavior includes harassment, discrimination, personal attacks,
+deliberate intimidation, unwanted contact, and publishing private information.
+
+Report conduct concerns privately to the repository maintainers through the
+security contact listed in [SECURITY.md](SECURITY.md). Do not use public issue
+discussion for sensitive reports.
+
+Maintainers may remove comments, close discussions, or restrict participation
+when necessary to protect the project community. They will explain moderation
+decisions when doing so is safe and appropriate.

silver_lang-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing To Silver
+
+Thank you for taking a look. Silver is intentionally small: the best
+contributions make one behavior clearer, more useful, or more testable without
+making the reference implementation harder to understand.
+
+The central idea is inspectability. A contribution should preserve as much of
+the following as the feature allows:
+
+- source behavior can be followed through syntax, IR, bytecode, VM, or traces;
+- agent workflows can be replayed and checked;
+- ML operations expose their data and gradients in the reference path;
+- public Python contracts say what callers can rely on;
+- tests demonstrate behavior rather than only checking object shape.
+
+## Before You Start
+
+Silver targets Python 3.9 or newer. Install the root development package and
+the companion package test dependencies with pip.
+
+## Local Development
+
+```bash
+python3 -m pip install -e '.[dev]' \
+  -e 'packages/data[dev,pandas]' \
+  -e 'packages/run[dev]' \
+  -e 'packages/diagnostics[dev]' \
+  -e 'packages/adapters[dev,remote]'
+python3 -m pytest tests packages/data/tests packages/run/tests packages/diagnostics/tests packages/adapters/tests
+python3 -m build
+```
+
+## Pull Request Bar
+
+- Add or update tests for language, runtime, compiler, agent, or ML changes.
+- Add docs for new syntax, agent semantics, public APIs, or ML behavior.
+- Do not introduce parser generators or hidden ML dependencies in the reference
+  path.
+- Keep deterministic traces stable unless the change intentionally updates the
+  trace schema.
+- Keep documentation honest about whether a feature executes today or is an
+  inspectable design contract.
+- Keep the change focused and explain its user-facing reason in the pull request.
+
+## How We Code Here
+
+- Keep low-level paths explicit.
+- Add convenience only when it teaches or removes real friction.
+- Write names a human would say out loud: `compileSilverMl`, `explain`, and
+  `stableDigest`.
+- Let tests describe the promise.
+- Prefer a small implementation over a general abstraction introduced for one
+  caller.
+
+## Good First Contributions
+
+- Add a regression test for an edge case in the language or VM.
+- Improve an example so a new user can run it without knowing the internals.
+- Add an executable ML operation with forward, gradient, serialization, and
+  inspection tests.
+- Turn one architecture blueprint into a small, deterministic executable model.
+- Improve error messages while preserving stable behavior where callers depend
+  on it.
+
+Please open an issue first for a broad architectural change. That gives the
+design a chance to settle before implementation begins.

silver_lang-0.1.0/LICENSE

@@ -0,0 +1,12 @@
+Apache License
+Version 2.0, January 2004
+
+Copyright 2026 Silver Contributors
+
+Licensed under the Apache License, Version 2.0. You may obtain a copy of the
+License at https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

silver_lang-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include SECURITY.md
+include CODE_OF_CONDUCT.md
+include CHANGELOG.md
+recursive-include silverlang *.py py.typed
+recursive-include docs *.md
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.py[cod]

silver_lang-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: silver-lang
+Version: 0.1.0
+Summary: From-scratch AI systems language with deterministic agents, ML graphs, and runtime traces.
+Author: Silver Contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/adfgdartec/silver-lang
+Project-URL: Repository, https://github.com/adfgdartec/silver-lang
+Project-URL: Issues, https://github.com/adfgdartec/silver-lang/issues
+Project-URL: Documentation, https://github.com/adfgdartec/silver-lang#readme
+Keywords: language,compiler,agents,machine-learning,deterministic-runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# Silver
+
+Silver is a small, inspectable language and machine-learning toolkit for
+Python.
+
+The Silver ecosystem also includes lightweight Python packages for datasets,
+training lifecycles, diagnostics, and bridges to PyTorch, TensorFlow, Keras,
+notebooks, and remote jobs. Start with [Choose your Silver path](docs/choose-your-path.md)
+to install only what your project needs.
+
+It is for people who want to see what a program, model, compiler, or agent is
+doing instead of handing the important parts to opaque infrastructure. Silver
+keeps source structure, intermediate representations, tensor operations,
+execution traces, and model metadata available to the caller.
+
+Silver is useful for:
+
+- teaching language runtimes, compilers, autodiff, and neural networks;
+- building deterministic experiments and replayable agent workflows;
+- inspecting a model while it runs, not only reading its final prediction;
+- prototyping small Python tools without a large native ML dependency;
+- explaining how a larger architecture is organized before choosing a heavy
+  production backend.
+
+It is not a replacement for PyTorch, TensorFlow, or a hosted model service.
+Some larger architecture APIs are deliberately inspectable blueprints. The
+executable reference path currently focuses on the language runtime, tensors,
+autodiff, dense classifiers, ML source compilation, and TinyGPT.
+
+## Install From PyPI
+
+```bash
+python -m pip install silver-lang
+```
+
+Requirements: Python 3.9 or newer.
+
+## First Program
+
+```python
+from silverlang import build_pipeline, run_source
+
+source = """
+fn main():
+    value = 6 * 7
+    return value
+"""
+
+print(run_source(source).value)
+print(build_pipeline(source).to_json())
+```
+
+The runtime supports functions, assignments, integer literals, variables,
+arithmetic, returns, deterministic traces, tokenization, source digests, and
+execution manifests. Use `explain()` when you want to understand what happened,
+not only get a value back.
+
+## A Small ML Experiment
+
+The executable reference implementation is Python:
+
+```python
+from silverlang import build_pipeline
+
+artifacts = build_pipeline(source)
+print(artifacts.to_json())
+```
+
+## Inspectable ML
+
+The native ML implementation includes deterministic dense layers, ReLU,
+sigmoid and linear activations, softmax classifier output, single-sample SGD,
+cross-entropy training, tensor operations, reverse-mode autodiff, neuron
+inspection, model graphs, tensor graph metadata, gradient checks, named
+datasets, deterministic TinyGPT generation, and virtual large-model profiles.
+
+```python
+from silverlang.ml.tensor import Tensor
+
+tensor = Tensor.vector_grad(1, -2, 3).relu().sum()
+tensor.backward()
+print(tensor.inspect())
+```
+
+The package also has blueprints for Transformer, recurrent, CNN, autoencoder,
+GAN, diffusion, mixture-of-experts, retrieval-augmented, and hybrid systems.
+These describe components, dimensions, estimated scale, and composition
+boundaries. They do not allocate or train those large architectures yet.
+
+For a model-level explanation, use the computed inspection and translation
+helpers:
+
+```python
+from silverlang import teach_network
+
+study = teach_network()
+print(study.summary)
+```
+
+## Try the CLI
+
+```bash
+silver run program.sv
+```
+
+The CLI prints a deterministic execution manifest as JSON, which makes a small
+Silver program easy to inspect in a terminal or CI job.
+
+## Test Before Publishing
+
+Friends can test the exact package artifacts without publication:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+```
+
+The companion packages are built from their own directories:
+
+```bash
+python build_packages.py
+```
+
+The generated wheels and source archives can then be installed by a separate
+Python project.
+
+## Develop Silver
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+```
+
+The test suite exercises the Python compiler, VM, runtime, and ML paths. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow and
+[docs/index.md](docs/index.md) for topic-focused guides.
+
+## Publish the Package Family
+
+The root checkout is an umbrella repository. Export the six standalone package
+repositories with:
+
+```bash
+python scripts/export_repositories.py --owner YOUR_GITHUB_OWNER
+```
+
+The script creates local repositories with package-specific CI and PyPI release
+workflows. It never creates remotes or pushes credentials. Follow
+[docs/publishing.md](docs/publishing.md) for the exact GitHub and PyPI steps.
+
+## Public API
+
+The root `silverlang` package exports the lexer, parser, compiler pipeline,
+stack VM, runtime traces, visualization helpers, agent/workbench helpers, and
+the inspectable tensor and neural-network teaching modules. Lower-level
+modules include `silverlang.frontend`, `silverlang.ir`, `silverlang.bytecode`,
+`silverlang.vm`, and `silverlang.ml`.
+
+Read [docs/api.md](docs/api.md) for examples, [docs/language/syntax.md](docs/language/syntax.md)
+for the language surface, and [docs/ml/tiny-gpt.md](docs/ml/tiny-gpt.md) for a
+small model walkthrough. See [docs/ecosystem.md](docs/ecosystem.md) for the
+separate-package roadmap.
+
+## Project Boundaries
+
+Silver favors a small reference implementation with visible contracts over a
+large dependency graph. The package includes language execution, compiler and
+bytecode inspection, a stack VM, memory utilities, graph and package models,
+replayable agent workflows, application planning, module loading, IDE models,
+and the native ML paths described above.
+
+Specialized ML estimators such as Adam, unsupervised learning, reinforcement
+learning, regression, and full executable CNN, Transformer, GAN, and diffusion
+backends are future work. Contributions that make one of those paths real,
+tested, and explainable are especially valuable.
+
+## License
+
+Silver is distributed under the [Apache License 2.0](LICENSE).

silver_lang-0.1.0/README.md

@@ -0,0 +1,181 @@
+# Silver
+
+Silver is a small, inspectable language and machine-learning toolkit for
+Python.
+
+The Silver ecosystem also includes lightweight Python packages for datasets,
+training lifecycles, diagnostics, and bridges to PyTorch, TensorFlow, Keras,
+notebooks, and remote jobs. Start with [Choose your Silver path](docs/choose-your-path.md)
+to install only what your project needs.
+
+It is for people who want to see what a program, model, compiler, or agent is
+doing instead of handing the important parts to opaque infrastructure. Silver
+keeps source structure, intermediate representations, tensor operations,
+execution traces, and model metadata available to the caller.
+
+Silver is useful for:
+
+- teaching language runtimes, compilers, autodiff, and neural networks;
+- building deterministic experiments and replayable agent workflows;
+- inspecting a model while it runs, not only reading its final prediction;
+- prototyping small Python tools without a large native ML dependency;
+- explaining how a larger architecture is organized before choosing a heavy
+  production backend.
+
+It is not a replacement for PyTorch, TensorFlow, or a hosted model service.
+Some larger architecture APIs are deliberately inspectable blueprints. The
+executable reference path currently focuses on the language runtime, tensors,
+autodiff, dense classifiers, ML source compilation, and TinyGPT.
+
+## Install From PyPI
+
+```bash
+python -m pip install silver-lang
+```
+
+Requirements: Python 3.9 or newer.
+
+## First Program
+
+```python
+from silverlang import build_pipeline, run_source
+
+source = """
+fn main():
+    value = 6 * 7
+    return value
+"""
+
+print(run_source(source).value)
+print(build_pipeline(source).to_json())
+```
+
+The runtime supports functions, assignments, integer literals, variables,
+arithmetic, returns, deterministic traces, tokenization, source digests, and
+execution manifests. Use `explain()` when you want to understand what happened,
+not only get a value back.
+
+## A Small ML Experiment
+
+The executable reference implementation is Python:
+
+```python
+from silverlang import build_pipeline
+
+artifacts = build_pipeline(source)
+print(artifacts.to_json())
+```
+
+## Inspectable ML
+
+The native ML implementation includes deterministic dense layers, ReLU,
+sigmoid and linear activations, softmax classifier output, single-sample SGD,
+cross-entropy training, tensor operations, reverse-mode autodiff, neuron
+inspection, model graphs, tensor graph metadata, gradient checks, named
+datasets, deterministic TinyGPT generation, and virtual large-model profiles.
+
+```python
+from silverlang.ml.tensor import Tensor
+
+tensor = Tensor.vector_grad(1, -2, 3).relu().sum()
+tensor.backward()
+print(tensor.inspect())
+```
+
+The package also has blueprints for Transformer, recurrent, CNN, autoencoder,
+GAN, diffusion, mixture-of-experts, retrieval-augmented, and hybrid systems.
+These describe components, dimensions, estimated scale, and composition
+boundaries. They do not allocate or train those large architectures yet.
+
+For a model-level explanation, use the computed inspection and translation
+helpers:
+
+```python
+from silverlang import teach_network
+
+study = teach_network()
+print(study.summary)
+```
+
+## Try the CLI
+
+```bash
+silver run program.sv
+```
+
+The CLI prints a deterministic execution manifest as JSON, which makes a small
+Silver program easy to inspect in a terminal or CI job.
+
+## Test Before Publishing
+
+Friends can test the exact package artifacts without publication:
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+```
+
+The companion packages are built from their own directories:
+
+```bash
+python build_packages.py
+```
+
+The generated wheels and source archives can then be installed by a separate
+Python project.
+
+## Develop Silver
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m build
+```
+
+The test suite exercises the Python compiler, VM, runtime, and ML paths. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow and
+[docs/index.md](docs/index.md) for topic-focused guides.
+
+## Publish the Package Family
+
+The root checkout is an umbrella repository. Export the six standalone package
+repositories with:
+
+```bash
+python scripts/export_repositories.py --owner YOUR_GITHUB_OWNER
+```
+
+The script creates local repositories with package-specific CI and PyPI release
+workflows. It never creates remotes or pushes credentials. Follow
+[docs/publishing.md](docs/publishing.md) for the exact GitHub and PyPI steps.
+
+## Public API
+
+The root `silverlang` package exports the lexer, parser, compiler pipeline,
+stack VM, runtime traces, visualization helpers, agent/workbench helpers, and
+the inspectable tensor and neural-network teaching modules. Lower-level
+modules include `silverlang.frontend`, `silverlang.ir`, `silverlang.bytecode`,
+`silverlang.vm`, and `silverlang.ml`.
+
+Read [docs/api.md](docs/api.md) for examples, [docs/language/syntax.md](docs/language/syntax.md)
+for the language surface, and [docs/ml/tiny-gpt.md](docs/ml/tiny-gpt.md) for a
+small model walkthrough. See [docs/ecosystem.md](docs/ecosystem.md) for the
+separate-package roadmap.
+
+## Project Boundaries
+
+Silver favors a small reference implementation with visible contracts over a
+large dependency graph. The package includes language execution, compiler and
+bytecode inspection, a stack VM, memory utilities, graph and package models,
+replayable agent workflows, application planning, module loading, IDE models,
+and the native ML paths described above.
+
+Specialized ML estimators such as Adam, unsupervised learning, reinforcement
+learning, regression, and full executable CNN, Transformer, GAN, and diffusion
+backends are future work. Contributions that make one of those paths real,
+tested, and explainable are especially valuable.
+
+## License
+
+Silver is distributed under the [Apache License 2.0](LICENSE).

silver_lang-0.1.0/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+Silver is alpha software. Do not run untrusted Silver programs or agent tools in
+privileged environments.
+
+## Supported Versions
+
+| Version | Supported                 |
+| ------- | ------------------------- |
+| 0.1.x   | Security reports accepted |
+
+## Reporting
+
+Please report security issues through the repository issue tracker:
+
+https://github.com/adfgdartec/silver.sv/issues
+
+Include:
+
+- affected commit or release;
+- operating system and Python version;
+- proof of concept or reproduction steps;
+- expected and actual behavior;
+- whether the issue can affect deterministic replay, trace integrity, package
+  builds, or agent tool execution.
+
+## Security Principles
+
+- No hidden runtime execution.
+- No network access in the reference compiler/runtime path.
+- No parser generators or dynamic reflection dispatch in the language core.
+- Agent tool calls must be explicit, bounded, logged, and replayable.
+- Build outputs must be reproducible from source files.

silver_lang-0.1.0/docs/agents/contracts.md

@@ -0,0 +1,25 @@
+# Silver Agent Contracts
+
+Silver agents are replayable graph nodes in the native Python runtime.
+
+Each agent has a name, bounded execution loop, ordered tool registry, workspace
+memory, messages, append-only trace events, and replay digests.
+
+```js
+import { Agent, AgentWorkflow } from "silver-lang/platform";
+
+const researcher = new Agent(
+  "researcher",
+  async (value, context) => context.tool("memory.lookup", value),
+  { "memory.lookup": async (value) => ({ value, source: "workspace" }) },
+);
+
+const workflow = new AgentWorkflow();
+workflow.add(researcher);
+const result = await workflow.run("protein");
+console.log(result.replay(), result.verifyReplay());
+```
+
+Each step records the selected tool, inputs, outputs, workspace writes, message
+traffic, and stable payload digests. This makes workflows inspectable and
+repeatable without hiding execution behind a framework.

silver_lang-0.1.0/docs/api.md

@@ -0,0 +1,54 @@
+# Public API
+
+Silver is distributed as the `silver-lang` Python package on PyPI. Its import
+package is `silverlang`.
+
+## Language Runtime
+
+```python
+from silverlang import Lexer, build_pipeline, run_source
+
+source = "fn main():\n    return 2 + 3\n"
+tokens = Lexer(source).lex()
+artifacts = build_pipeline(source)
+value = run_source(source)
+```
+
+The root API exposes tokenization, compilation, execution, deterministic traces,
+source digests, and execution manifests.
+
+## ML
+
+```python
+from silverlang.ml.tensor import Tensor
+
+tensor = Tensor.vector_grad(1, -2, 3).relu().sum()
+tensor.backward();
+```
+
+## Platform Modules
+
+The package also exposes `silverlang.platform`, `silverlang.ir`,
+`silverlang.pipeline`, and `silverlang.vm` for package management, graphs,
+agents/workflows, compiler/bytecode inspection, and deterministic stack-machine
+execution.
+
+## Inspection and Model Families
+
+```python
+from silverlang import teach_network
+
+study = teach_network()
+print(study.summary)
+```
+
+The model-family blueprints are metadata and graph contracts, not claims that
+the package allocates a trillion-parameter model in memory. They make the
+attention pattern, component boundaries, estimated scale, and composition
+choices inspectable before an execution backend is selected.
+
+## CLI
+
+```bash
+silver run program.sv
+```

silver_lang-0.1.0/docs/architecture/diamond-design.md

@@ -0,0 +1,35 @@
+# Silver Diamond Design
+
+Silver exists for people building AI systems that need to be understood, not
+just executed.
+
+## System Shape
+
+```text
+source.sv
+  -> handwritten lexer
+  -> recursive-descent parser
+  -> AST
+  -> explicit IR
+  -> optimizer
+  -> bytecode
+  -> deterministic VM
+  -> trace log
+  -> agent/model/deployment evidence
+```
+
+## Diamond Principles
+
+1. AI systems are graphs, so Silver stores computation as visible graph events.
+2. Agents are deterministic workflows by default, not opaque loops.
+3. Models can be trained elsewhere later, but the reference path must be
+   inspectable from scratch.
+4. Native Python modules share trace contracts instead of hiding
+   implementation details behind external runtimes.
+5. Every optimization must preserve observable traces or explain why not.
+
+## Non-Goals For The Initial Rewrite
+
+- No dependency on LLVM, parser generators, PyTorch, TensorFlow, or NumPy.
+- No claim that the tiny GPT reference model is competitive.
+- No hidden tool execution or nondeterministic agent behavior by default.