Metadata-Version: 2.4
Name: silver-lang
Version: 0.3.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

See [the supervised-learning cookbook](docs/supervised-learning.md) for a
complete dataset-to-model-to-GPU-to-diagnostics example covering the package
family.

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).
