synthedu 1.5.0

Agent-Based Synthetic Educational Data Generation for ODL Research

SynthEd: From synthetic data to simulated learners

Agent-based simulation environment for Open & Distance Learning (ODL) research. SynthEd generates behaviorally grounded and temporally coherent learning trajectories by combining persona-driven agent modeling with 10 established theoretical frameworks. Built for researchers in learning analytics, educational data mining, and dropout prediction.

pip install -e ".[dev]"
python run_pipeline.py --n 200      # or: pip install synthedu

From statistical similarity to behavioral fidelity. Traditional synthetic data methods optimize for distributional match. SynthEd optimizes for behavioral coherence -- each data point emerges from a simulated student's evolving motivations, decisions, and life context.

---

Why SynthEd?

Challenge	Traditional Approach	SynthEd Approach
Privacy regulations (GDPR/KVKK)	Anonymization (re-identification risk)	Agents are fictional -- no real individuals
Class imbalance in dropout data	Oversampling (SMOTE) -- loses context	Parameter-level control of dropout rates
Temporal incoherence	GAN/VAE post-hoc smoothing	Persona + memory produces coherent trajectories

---

Key Features

• 10 Theory Modules -- Tinto, Bean & Metzner, Kember, SDT, Garrison CoI, Moore, Rovai, Baulke, Epstein & Axtell, Gonzalez (+ unavoidable withdrawal mechanism)
• Trait-Based Calibration -- Sobol sensitivity (69 params) + NSGA-II multi-objective optimization against real OULAD data
• Multi-Semester Simulation -- Carry-over mechanics for engagement, GPA, coping, dropout phases
• GPA Feedback Loop -- Cumulative GPA anchors cost-benefit, non-fit perception, and competence beliefs
• OULAD-Compatible Export -- 7-table CSV matching the Open University Learning Analytics Dataset schema
• Adaptive Parameter Bounds -- auto_bounds() adjusts calibration space when demographics change
• 5-Level Validation Suite -- 21 statistical tests (distributions, correlations, temporal coherence, privacy, backstory)
• Optional LLM Enrichment -- Persona-grounded narrative backstories via OpenAI, Ollama, or any compatible provider
• Default Benchmark Profile -- Customizable via PersonaConfig, InstitutionalConfig, GradingConfig with CLI report generation
• InstitutionalConfig -- 5 institution-level quality parameters that modulate theory constants
• GradingConfig -- Configurable grading policy: Beta/Normal/Uniform grade distributions, weighted semester grades (midterm/final), dual-hurdle pass requirements, exam-only and continuous assessment modes, floor-adjusted transcript scale for outcome classification (Distinction/Pass/Fail)
• EngineConfig -- 70 frozen engine constants with validation (weight sums, ordering, positivity), overridable via dataclasses.replace()
• NSGA-II Calibration -- Multi-objective optimization with Pareto front, parallel --workers N support
• Relative Grading -- grading_method="relative" with t-score cohort normalization, automatic fallback for small/homogeneous cohorts
• Baulke Institutional Modulation -- support_services_quality scales 13 dropout phase thresholds, better institutions produce lower dropout
• PipelineConfig -- Frozen dataclass grouping 16 pipeline params with JSON to_dict()/from_dict() serialization for reproducibility
• TheoryModule Protocol -- Phase-based dispatch with auto-discovery, new theories added with zero engine changes

---

Quick Start

git clone https://github.com/theaiagent/SynthEd.git
cd SynthEd
pip install -e ".[dev]"              # Dev install (no LLM)
pip install -e ".[dev,llm]"          # Dev install with LLM support
python run_pipeline.py              # 200 students, 14 weeks
python run_pipeline.py --n 500      # Custom population
python run_pipeline.py --oulad      # OULAD-compatible export
python run_pipeline.py --benchmark  # Run default benchmark profile
python run_calibration.py --workers 4  # Parallel NSGA-II calibration

from synthed.pipeline import SynthEdPipeline
from synthed.pipeline_config import PipelineConfig

config = PipelineConfig(output_dir="./output", seed=42)
pipeline = SynthEdPipeline(config=config)
report = pipeline.run(n_students=300)
print(f"Dropout: {report['simulation_summary']['dropout_rate']:.1%}")

---

Use Cases

1. Dropout Prediction -- Generate labeled training data with known ground-truth trajectories
2. Intervention Simulation -- Model "what-if" scenarios by adjusting population parameters
3. Privacy-Safe Benchmarking -- Share synthetic datasets publicly for reproducible research

---

Documentation

Document	Content
User Guide	Installation, configuration, calibration pipeline, OULAD export, LLM enrichment, troubleshooting
Theory & Architecture	10 theoretical anchors, factor clusters, architecture diagram, project structure, validation suite, test inventory

---

Roadmap

• Multi-semester simulation with carry-over
• 10 theory modules (Tinto, Bean & Metzner, Kember, SDT, Garrison, Moore, Rovai, Baulke, Epstein & Axtell, Gonzalez)
• Trait-based calibration (Sobol + Optuna + OULAD validation)
• Benchmark reports with CLI (--benchmark)
• OULAD-compatible 7-table export
• LLM enrichment with cost control and streaming
• Disability severity (Beta distribution)
• InstitutionalConfig (5 quality parameters modulating theory constants)
• NSGA-II multi-objective calibration with Pareto front
• Spectrum refactoring (binary -> continuous for family/internet)
• GraphRAG integration (curriculum modeling)
• LLM-augmented mode (forum posts, assignment text)
• Parquet/Arrow export
• PyPI package publication (pip install synthedu)
• Interactive dashboard

---

Legal Disclaimer

SynthEd generates entirely fictional synthetic data. No real individuals are represented or identifiable. Outputs are intended for research, development, and educational purposes. SynthEd is under active development -- APIs and output formats may change between versions.

See full Legal Disclaimer and Responsible Use guidelines.

---

Contributing

Contributions welcome! See the User Guide for development setup.

ruff check synthed/ tests/
python -m pytest tests/ -v --tb=short

---

License

MIT License. See LICENSE.

Citation

If you use SynthEd in your research, please cite using the CITATION.cff file or the Zenodo DOI above.

Contributors

Contributor	Role
Halis Aykut Cosgun	Lead Developer, Data Scientist & AI Engineer, Researcher -- Yozgat Bozok University
Evrim Genc Kumtepe	Research Advisor -- Anadolu University
Claude (Anthropic)	AI pair programmer -- implementation, testing, code review

Acknowledgments

Conceptually inspired by TinyTroupe (Microsoft), MiroFish, and Agent Lightning. OULAD reference data: Kuzilek et al. (2017).