Metadata-Version: 2.4
Name: sampleplan
Version: 0.1.0
Summary: Fast balanced sequence sampling via a compiled Nim backend
Author-email: Maxime Larocque <maxime.larocque@randomschemes.com>
License: MIT
Keywords: sampling,random,balanced,permutation,simulation,nim,ctypes
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Operating System :: Microsoft :: Windows
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Dynamic: license-file

# ⚖️ SamplePlan — Nim-Powered Balanced Sampler for Python

[![TestPyPI](https://img.shields.io/badge/TestPyPI-package-informational?logo=pypi)](https://test.pypi.org/project/sampleplan/)

A blazing-fast compiled backend for generating balanced random sequences in
Python. Built using [Nim](https://nim-lang.org/) and exposed via `ctypes`.
Ideal for simulations, experimental design, or randomized testing scenarios
where equal representation of categories is required.

## 🚧 Note

> This is a lightweight, low-level library that demonstrates how to integrate
> compiled Nim code with Python. It exposes a single high-performance utility
> for generating balanced permutations, useful in simulation, randomization,
> and probabilistic workflows.

## 🚀 Features

- ⚡ Fast compiled DLL backend (Nim → C → Python)
- 📦 Seamless Python interface via `ctypes`
- 🧮 Returns balanced permutations of symbols
- 🧪 Deterministic output with `seed`

## 📦 Setup

Install Python and [Nim](https://nim-lang.org/) if you intend to rebuild the
shared library from source.

Create your virtual environment:

```bash
python -m venv venv
```

Then activate it:

```bash
venv\Scripts\activate
```

Install the project's dependencies from the requirements file, if any:

```bash
python -m pip install -r requirements.txt
```

## 🐍 Python Usage

Install the local package:

```bash
python -m pip install -e .
```

Then use it. This call returns a `3 × 6` NumPy array (3 simulations of 2 × 3
symbols):

```python
from sampleplan import sample_balanced

out = sample_balanced(["A", "B", "C"], m=2, size=3, seed=42)
print(out)
# array([
#   ['A', 'B', 'C', 'C', 'B', 'A'],
#   ['B', 'C', 'A', 'A', 'B', 'C'],
#   ['C', 'A', 'B', 'B', 'C', 'A']
# ])
```

## 🧱 Underlying C Signature

This function accepts raw memory buffers from Python and writes directly into
the pre-allocated output array. It is not meant to be called directly from user
code.

```c
void sampleBalanced(
    int* symbols, int symbolCount, int m, int size, int seed, int* outSeq
);
```

All pointer data is managed from the Python side using NumPy and ctypes.

## 🏗️ Build the DLL (Windows)

Compile the DLL using the Nim compiler and Microsoft's Visual C++ (MSVC)

```bash
nim c --cc:vcc --app:lib --out:sampler/sampleplan.dll build/sampleplan.nim
```

For faster release builds:

```bash
nim c --cc:vcc --app:lib --out:sampleplan/sampleplan.dll -d:release build/sampleplan.nim
```

This generates `sampleplan.dll`, which is required for Python execution.

## 📦 Packaging and Distribution

To build the Python wheel:

```bash
python -m build --wheel
```

### Optional: Build a Windows-specific wheel manually using platform tag

```bash
python -m pip wheel --platform win_amd64 .
```

## 📁 Project Structure

```bash
sampleplan/
├── __init__.py
├── sampleplan.py            # Python interface to the DLL
├── sampleplan.dll           # Compiled Nim shared library
build/
└── sampleplan.nim           # Nim source code (not distributed)
tests/
└── test_sampler.py
pyproject.toml
LICENSE
MANIFEST.in
README.md
```

## ⚠️ Platform Support

- ✅ Windows
- ⏳ Linux and macOS coming soon

## 🧠 License

MIT — use freely, cite kindly. See [LICENSE](LICENSE).

## 📋 Design Quality Summary

| Area | Upgrade |
|------|---------|
| 🔍 Clarity | Clear description of purpose and how to use it |
| 🧪 Example | Shows expected behavior with `sample_balanced` |
| 📦 Structure | Documents project folder layout |
| ⚠️ Platform | Transparently marks this as Windows-only |
| 🧠 Professionalism | Adds a polished voice and structure for PyPI or GitHub |
