# silvermete0r/oikan architecture

> Architecture diagram of the GitHub repository silvermete0r/oikan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/silvermete0r/oikan
- Repository: https://github.com/silvermete0r/oikan

## Overview

#### Purpose and Public Entry Points
OIKAN is a Python neuro-symbolic ML library for tabular regression and classification. Its public estimators expose scikit-learn-style `fit`, `predict`, `score`, formula retrieval, feature importance, and JSON persistence APIs. Package exports begin at `oikan/__init__.py`; estimator orchestration is centered in `oikan/model.py`.

#### Estimator Orchestration
`OIKANRegressor` and `OIKANClassifier` coordinate the end-to-end workflow: validate inputs, train/evaluate an auxiliary neural model, augment data, fit symbolic models, and expose inference/export interfaces. Classification must manage a separate symbolic model per class; regression yields one coefficient vector.
- `oikan/model.py`
- `oikan/__init__.py`
- `oikan/exceptions.py`

#### Neural Learning and Augmentation Boundary
A PyTorch tabular neural network provides learned predictions used to augment original training data with noisy/generated samples. This neural stage supports configurable hidden layers, activations, batching, epochs, learning rate, optional GPU use, and pre-symbolic evaluation. The neural model is auxiliary; exported inference is intended to rely on symbolic formulas rather than PyTorch weights.
- `oikan/neural.py`
- `oikan/model.py`

#### Symbolic Feature Construction and Sparse Regression
The symbolic layer expands input features into interpretable basis terms—polynomials, interactions, trigonometric, exponential, and logarithmic transforms—then applies ElasticNet regularization to select/prune terms. Coefficients and retained basis metadata form the deployable model representation.
- `oikan/elasticnet.py`
- `oikan/utils.py`
- `oikan/model.py`

#### Formula and Model Serialization
Selected basis functions plus coefficients are rendered as original symbolic strings or transformed through SymPy into simplified and LaTeX formats. Model save/load uses JSON artifacts containing feature counts, basis-function metadata, and regression coefficients or classification coefficient lists.
- `oikan/model.py`
- `outputs/california_housing_model.json`
- `outputs/iris_model.json`

#### Cross-Language Deployment Compilers
Language-specific compiler implementations consume exported symbolic-model JSON and reproduce basis evaluation plus linear prediction. Regression compilers return a scalar/vector prediction; classifier compilers compute class logits, softmax probabilities, and argmax labels. Each target language maintains distinct regression and classification implementations.
- `model_compilers/python/regression_compiler.py`
- `model_compilers/cpp/classification_compiler.cpp`
- `model_compilers/rust/regression_compiler.rs`

#### Runtime, Dependencies, and Delivery
The primary runtime is Python 3.11+ with PyTorch for neural training, NumPy for arrays, scikit-learn for ElasticNet/estimator conventions, and SymPy for formula formatting. The project is distributed as a PyPI package through `pyproject.toml`/`setup.py`; static documentation is published from `docs/`, with GitHub Actions static-site automation.
- `pyproject.toml`
- `requirements.txt`
- `setup.py`

Main entry points: [`oikan/model.py`](https://github.com/silvermete0r/oikan/blob/main/oikan/model.py) (Regressor & classifier), [`outputs/california_housing_model.json`](https://github.com/silvermete0r/oikan/blob/main/outputs/california_housing_model.json) (Model JSON artifacts), [`oikan/__init__.py`](https://github.com/silvermete0r/oikan/blob/main/oikan/__init__.py) (Public package API), [`oikan/neural.py`](https://github.com/silvermete0r/oikan/blob/main/oikan/neural.py) (Auxiliary neural model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python library"]
  node_package["Public package API<br/>Python package<br/>[__init__.py]"]
  node_estimators["Regressor &amp; classifier<br/>Estimator orchestration<br/>[model.py]"]
  node_errors["Library exceptions<br/>Error boundary<br/>[exceptions.py]"]
  node_neural["Auxiliary neural model<br/>PyTorch tabular model<br/>[neural.py]"]
end

subgraph group_symbolic["Symbolic modeling"]
  node_basis["Basis expansion<br/>Symbolic features<br/>[utils.py]"]
  node_elasticnet["Sparse symbolic fitting<br/>ElasticNet model<br/>[elasticnet.py]"]
  node_formula["Formula rendering<br/>SymPy formatting<br/>[model.py]"]
end

subgraph group_deployment["Deployment targets"]
  node_artifacts["Model JSON artifacts<br/>Serialized model"]
  node_python_compiler["Python regression compiler<br/>Generated-model runtime"]
  node_cpp_compiler["C++ classifier compiler<br/>Generated-model runtime"]
  node_rust_compiler["Rust regression compiler<br/>Generated-model runtime"]
end

node_distribution["PyPI distribution<br/>Python packaging<br/>[pyproject.toml]"]

node_package -->|"exports"| node_estimators
node_estimators -->|"raises"| node_errors
node_estimators -->|"trains and evaluates"| node_neural
node_neural -->|"predictions augment data"| node_estimators
node_estimators -->|"builds terms"| node_basis
node_basis -->|"expanded features"| node_elasticnet
node_elasticnet -->|"coefficients and retained terms"| node_estimators
node_estimators -->|"renders formulas"| node_formula
node_estimators -->|"saves and loads JSON"| node_artifacts
node_artifacts -->|"consumed by"| node_python_compiler
node_artifacts -->|"consumed by"| node_cpp_compiler
node_artifacts -->|"consumed by"| node_rust_compiler
node_distribution -->|"packages"| node_package

click node_package "https://github.com/silvermete0r/oikan/blob/main/oikan/__init__.py"
click node_estimators "https://github.com/silvermete0r/oikan/blob/main/oikan/model.py"
click node_errors "https://github.com/silvermete0r/oikan/blob/main/oikan/exceptions.py"
click node_neural "https://github.com/silvermete0r/oikan/blob/main/oikan/neural.py"
click node_basis "https://github.com/silvermete0r/oikan/blob/main/oikan/utils.py"
click node_elasticnet "https://github.com/silvermete0r/oikan/blob/main/oikan/elasticnet.py"
click node_formula "https://github.com/silvermete0r/oikan/blob/main/oikan/model.py"
click node_artifacts "https://github.com/silvermete0r/oikan/blob/main/outputs/california_housing_model.json"
click node_python_compiler "https://github.com/silvermete0r/oikan/blob/main/model_compilers/python/regression_compiler.py"
click node_cpp_compiler "https://github.com/silvermete0r/oikan/blob/main/model_compilers/cpp/classification_compiler.cpp"
click node_rust_compiler "https://github.com/silvermete0r/oikan/blob/main/model_compilers/rust/regression_compiler.rs"
click node_distribution "https://github.com/silvermete0r/oikan/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_estimators,node_errors,node_neural toneBlue
class node_basis,node_elasticnet,node_formula toneAmber
class node_artifacts,node_python_compiler,node_cpp_compiler,node_rust_compiler toneMint
class node_distribution toneNeutral
```

## Components

### Python library

- [Public package API](https://github.com/silvermete0r/oikan/blob/main/oikan/__init__.py): Python package · Exports the estimator API. · `oikan/__init__.py`
- [Regressor & classifier](https://github.com/silvermete0r/oikan/blob/main/oikan/model.py): Estimator orchestration · Coordinates training, inference, formulas, and persistence. · `oikan/model.py`
- [Library exceptions](https://github.com/silvermete0r/oikan/blob/main/oikan/exceptions.py): Error boundary · `oikan/exceptions.py`
- [Auxiliary neural model](https://github.com/silvermete0r/oikan/blob/main/oikan/neural.py): PyTorch tabular model · Produces predictions for augmentation and pre-symbolic evaluation. · `oikan/neural.py`

### Symbolic modeling

- [Basis expansion](https://github.com/silvermete0r/oikan/blob/main/oikan/utils.py): Symbolic features · Builds interpretable polynomial and transformed terms. · `oikan/utils.py`
- [Sparse symbolic fitting](https://github.com/silvermete0r/oikan/blob/main/oikan/elasticnet.py): ElasticNet model · Selects basis terms and learns deployable coefficients. · `oikan/elasticnet.py`
- [Formula rendering](https://github.com/silvermete0r/oikan/blob/main/oikan/model.py): SymPy formatting · Renders selected terms as simplified and LaTeX formulas. · `oikan/model.py`

### Deployment targets

- [Model JSON artifacts](https://github.com/silvermete0r/oikan/blob/main/outputs/california_housing_model.json): Serialized model · Stores feature metadata and regression or per-class coefficients. · `outputs/california_housing_model.json`
- [Python regression compiler](https://github.com/silvermete0r/oikan/blob/main/model_compilers/python/regression_compiler.py): Generated-model runtime · Reproduces basis evaluation and linear regression prediction. · `model_compilers/python/regression_compiler.py`
- [C++ classifier compiler](https://github.com/silvermete0r/oikan/blob/main/model_compilers/cpp/classification_compiler.cpp): Generated-model runtime · Computes class logits, softmax probabilities, and labels. · `model_compilers/cpp/classification_compiler.cpp`
- [Rust regression compiler](https://github.com/silvermete0r/oikan/blob/main/model_compilers/rust/regression_compiler.rs): Generated-model runtime · Reproduces basis evaluation and linear regression prediction. · `model_compilers/rust/regression_compiler.rs`

### Other components

- [PyPI distribution](https://github.com/silvermete0r/oikan/blob/main/pyproject.toml): Python packaging · Defines the Python 3.11+ package and dependencies. · `pyproject.toml`

## Connections

- Public package API → Regressor & classifier: exports
- Regressor & classifier → Library exceptions: raises
- Regressor & classifier → Auxiliary neural model: trains and evaluates
- Auxiliary neural model → Regressor & classifier: predictions augment data
- Regressor & classifier → Basis expansion: builds terms
- Basis expansion → Sparse symbolic fitting: expanded features
- Sparse symbolic fitting → Regressor & classifier: coefficients and retained terms
- Regressor & classifier → Formula rendering: renders formulas
- Regressor & classifier → Model JSON artifacts: saves and loads JSON
- Model JSON artifacts → Python regression compiler: consumed by
- Model JSON artifacts → C++ classifier compiler: consumed by
- Model JSON artifacts → Rust regression compiler: consumed by
- PyPI distribution → Public package API: packages