Metadata-Version: 2.4
Name: silver-lang
Version: 1.3.0
Summary: Inspectable AI language and local ML workflow with live neural-network visual reports.
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,neural-networks,visualization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Provides-Extra: ecosystem
Requires-Dist: silver-data<2,>=1.3.0; extra == "ecosystem"
Requires-Dist: silver-diagnostics<2,>=1.3.0; extra == "ecosystem"
Requires-Dist: silver-run<2,>=1.3.0; extra == "ecosystem"
Requires-Dist: silver-torch[pytorch]<2,>=1.3.0; extra == "ecosystem"
Requires-Dist: silver-adapters<2,>=1.3.0; extra == "ecosystem"
Dynamic: license-file

# Silver

<p align="center">
  <img src="https://raw.githubusercontent.com/adfgdartec/silver-lang/main/docs/assets/silver-hero.png" alt="Silver — inspectable machine learning" width="100%">
</p>

<p align="center">
  <a href="https://pypi.org/project/silver-lang/"><img src="https://img.shields.io/pypi/v/silver-lang?color=7c3aed" alt="PyPI"></a>
  <a href="https://github.com/adfgdartec/silver-lang/actions/workflows/ci.yml"><img src="https://github.com/adfgdartec/silver-lang/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/adfgdartec/silver-lang/actions/workflows/ecosystem.yml"><img src="https://github.com/adfgdartec/silver-lang/actions/workflows/ecosystem.yml/badge.svg" alt="Ecosystem"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-c0c0c0" alt="Apache-2.0"></a>
</p>

**One local-first, inspectable path from raw data to a trained model—and a
language/runtime for understanding every layer underneath it.**

Silver 1.1 gives you dataset contracts, stratified splits, leakage-safe
preprocessing, real PyTorch training, durable experiment journals, best
checkpoints, drift detection, health scoring, framework adapters, and a complete
visual explanation of the network without requiring a hosted control plane.

The report also turns evidence into decisions: ranked fixes for data quality,
architecture, optimization, and generalization, each with an expected effect
and a verification test. Use `silver decisions .silver/experiment-report.json`
when you want the guidance as JSON instead of HTML.

## Every layer, explained

<p align="center"><img src="https://raw.githubusercontent.com/adfgdartec/silver-lang/main/docs/assets/neural-network-inspection.png" alt="Neural-network inputs, hidden layers, activations, gradients, prediction, and training health" width="100%"></p>

Every experiment now generates a standalone HTML dashboard plus six SVGs from
the actual run: feature flow, observed network layers and activations, layer
health, training health, and the durable run timeline. No hosted service and no
invented telemetry. Read the [visual report contract](docs/neural-visual-inspection.md).

## The 60-second path

```bash
python -m pip install 'silver-lang[ecosystem]'
silver init my-first-silver-project
cd my-first-silver-project
silver experiment silver-project.json
```

That command produces a model checkpoint, dataset contract, replayable JSONL
run journal, drift report, training-health assessment, consolidated JSON, six
evidence-backed SVGs, and `.silver/visual-report.html`.

```bash
silver doctor
silver runs .silver/runs
silver health metrics.json
silver report .silver/experiment-report.json
silver validate .silver/experiment-report.json --strict
```

## Why people keep Silver in the loop

| Need | Silver 1.1 |
|---|---|
| Know whether serving data still matches training | Portable contracts and explainable drift signals |
| Train without hiding the loop | Deterministic PyTorch trainer with callbacks and best-state restoration |
| Track experiments without deploying a server | Atomic checkpoints and append-only local run journals |
| Understand why training is unhealthy | Scored diagnostics with ranked remediation actions |
| See what every layer is doing | Shapes, parameters, activations, sparsity, gradients, and layer-health visuals |
| Connect existing tools safely | Discoverable adapters and shell-free JSONL subprocess bridges |
| See what code actually becomes | Lexer → AST → IR → optimizer → bytecode → VM traces |

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