title	CogniStep | Adaptive Learning Environment
emoji	🎓
colorFrom	blue
colorTo	indigo
sdk	docker
pinned	false
app_port	8000
base_path	/web
tags	openenv reinforcement-learning adaptive-learning edtech student-modeling ai python

🎓 CogniStep

An Adaptive Learning Environment for Reinforcement Learning Research

Teach smarter. Adapt continuously. Optimize learning outcomes.

GitHub Repository

---

Table of Contents

1. Introduction
2. Why CogniStep?
3. How Does It Work?
4. System Architecture
5. Reinforcement Learning Formulation
   • State Space
   • Action Space
   • Environment Dynamics
   • Reward Function
   • Episode Termination
6. Student Profiles
7. Installation
8. Quick Start
9. Environment API
10. Reinforcement Learning Integration
11. Evaluation and Benchmarking
12. Current Limitations
13. Future Roadmap
14. Project Structure
15. Deployment
16. Contributing
17. License

---

1. Introduction

CogniStep is an OpenEnv-compatible simulation environment designed to explore adaptive educational decision-making using reinforcement learning.

It simulates an AI teacher interacting with a virtual student over a sequence of learning activities.

At every step, an agent observes the student's current learning condition, selects an educational intervention, and receives feedback based on the resulting changes in the student's learning state.

Unlike traditional educational systems that follow predefined teaching sequences, CogniStep provides an environment for experimenting with teaching strategies that adapt to changing student conditions.

The simulation focuses on four important dimensions of learning:

Dimension	Description
Knowledge	How much the student currently knows
Attention	How well the student can concentrate
Fatigue	How much cognitive exhaustion has accumulated
Difficulty	How challenging the current learning material is

The objective is to investigate how intelligent agents can maximize learning progress while balancing cognitive fatigue, difficulty, and knowledge retention.

What Is the Core Idea?

Imagine an AI teacher interacting with three different students.

• One student understands concepts quickly and maintains high attention.
• Another student learns at a moderate pace and occasionally needs revision.
• A third student struggles with concentration, becomes tired quickly, and forgets previously learned concepts.

Should the AI teacher follow the same teaching strategy for all three?

Probably not.

An effective teaching system should continuously evaluate the student's condition and select an appropriate intervention.

CogniStep turns these educational decisions into a sequential decision-making problem.

What CogniStep Provides

• A simulated student learning environment.
• A discrete educational action space.
• Student state transitions.
• A reward calculation mechanism.
• Multiple predefined student profiles.
• An environment interface suitable for external agents.
• A foundation for experimenting with adaptive learning policies.

What CogniStep Does Not Yet Provide

CogniStep currently focuses on the environment rather than a complete reinforcement learning training framework.

Capability	Status
Student simulation	Implemented
Knowledge and attention modeling	Implemented
Fatigue and forgetting dynamics	Implemented
Educational action space	Implemented
Reward calculation	Implemented
Student profiles	Implemented
OpenEnv integration	Implemented
PPO training pipeline	Not implemented
DQN training pipeline	Not implemented
Pre-trained RL agent	Not included
Validated research benchmarks	Not established

Important: PPO, DQN, and other reinforcement learning algorithms can be integrated with CogniStep, but they are not currently bundled training implementations.

---

2. Why CogniStep?

Traditional educational systems often use fixed learning paths.

Every student may receive the same sequence of lessons, quizzes, and revision activities regardless of their individual learning conditions.

However, effective teaching requires continuous decisions.

For example:

• Should the teacher introduce a new concept?
• Should the student be tested?
• Is revision more valuable than introducing new material?
• Is the current difficulty too high?
• Is the student becoming fatigued?
• Should the system slow down or increase the learning challenge?

These decisions can be modeled as an optimization problem.

The agent attempts to discover a teaching strategy that maximizes long-term learning outcomes.

The Problem Being Explored

The central question behind CogniStep is:

Can an intelligent agent learn how to teach different students differently by interacting with a simulated learning environment?

The project provides an experimental foundation for investigating this question.

---

3. How Does It Work?

CogniStep follows an agent-environment interaction loop.

At every time step:

1. The agent receives the current student observation.
2. The agent selects an educational action.
3. The environment processes the selected action.
4. The student's learning state is updated.
5. The environment calculates a reward.
6. The next observation is returned to the agent.
7. The process continues until the episode terminates.

Interaction Flow

                 START EPISODE
                       |
                       v
             +-------------------+
             | Initialize Student|
             +---------+---------+
                       |
                       v
             +-------------------+
             | Student Observation|
             |                   |
             | Knowledge         |
             | Attention         |
             | Fatigue           |
             | Difficulty        |
             +---------+---------+
                       |
                       v
             +-------------------+
             |    AI Agent       |
             |                   |
             | Select Action     |
             +---------+---------+
                       |
                       v
             +-------------------+
             | Teaching Action   |
             |                   |
             | Teach / Quiz      |
             | Revise / Adjust   |
             +---------+---------+
                       |
                       v
             +-------------------+
             | Student Dynamics  |
             |                   |
             | Knowledge Update  |
             | Attention Update  |
             | Fatigue Update    |
             | Forgetting        |
             +---------+---------+
                       |
                       v
             +-------------------+
             | Reward Calculation|
             +---------+---------+
                       |
                       v
             +-------------------+
             | Next Observation  |
             | Reward / Done     |
             +---------+---------+
                       |
                       v
                 Episode Done?
                  /       \
                No         Yes
                |           |
                +-----------+
                     |
                     v
                    END

Example Interaction

Suppose the agent receives the following student state:

Parameter	Value
Knowledge	35
Attention	0.85
Fatigue	0.10
Difficulty	3

The agent selects:

teach

The environment then:

1. Calculates knowledge gain using the student's attention.
2. Increases fatigue.
3. Updates attention based on fatigue.
4. Applies random attention fluctuations.
5. Applies knowledge forgetting.
6. Calculates the reward.
7. Returns the updated student state.

The agent can then decide whether to teach again, conduct a quiz, revise the material, or adjust the difficulty.

This interaction continues throughout the episode.

---

4. System Architecture

CogniStep separates the environment from the decision-making agent.

This allows different agent architectures to interact with the same simulated student.

+------------------------------------------------+
|                  EXTERNAL AGENT                |
|                                                |
|       PPO / DQN / A2C / LLM / Custom Policy     |
+------------------------+-----------------------+
                         |
                         | Selected Action
                         v
+------------------------------------------------+
|                  OPENENV LAYER                 |
|                                                |
|               Reset / Step / State             |
+------------------------+-----------------------+
                         |
                         v
+------------------------------------------------+
|               COGNISTEP ENVIRONMENT            |
|                                                |
|  +------------------------------------------+  |
|  |              STUDENT MODEL               |  |
|  |                                          |  |
|  | Knowledge     Attention     Fatigue       |  |
|  | Difficulty    Forgetting                |  |
|  +------------------------------------------+  |
|                                                |
|  +------------------------------------------+  |
|  |              ACTION ENGINE              |  |
|  |                                          |  |
|  | Teach / Quiz / Revise / Adjust           |  |
|  +------------------------------------------+  |
|                                                |
|  +------------------------------------------+  |
|  |              REWARD ENGINE               |  |
|  +------------------------------------------+  |
|                                                |
|  +------------------------------------------+  |
|  |             EPISODE MANAGER              |  |
|  +------------------------------------------+  |
+------------------------+-----------------------+
                         |
                         | Observation + Reward
                         v
                  NEXT AGENT DECISION

Main Components

Component	Responsibility
Environment Engine	Maintains student state and executes transitions
Student Model	Simulates learning, attention, fatigue, and forgetting
Action Engine	Processes teaching interventions
Reward Engine	Evaluates learning outcomes and associated penalties
Episode Manager	Tracks steps and episode termination
OpenEnv Interface	Exposes standardized environment interaction

The agent is external to the environment. Its policy optimization and model training are separate responsibilities.

---

5. Reinforcement Learning Formulation

CogniStep can be formulated as a Markov Decision Process (MDP).

An MDP is commonly represented as:

M = (S, A, T, R, γ)

Where:

Symbol	Meaning
S	State space
A	Action space
T	State transition function
R	Reward function
γ	Discount factor

The environment implements student simulation, action transitions, and reward calculation.

The discount factor and policy optimization are configured by the external learning algorithm.

5.1 State Space

The student state is represented using four primary variables.

Sₜ = [Kₜ, Aₜ, Fₜ, Dₜ]

Where:

• Kₜ: Current knowledge level.
• Aₜ: Current attention level.
• Fₜ: Current fatigue level.
• Dₜ: Current difficulty level.

Observation Parameters

Parameter	Range	Description
knowledge	0–100	Current student knowledge
attention	0.3–1.0	Current concentration
fatigue	0–1.0	Accumulated cognitive fatigue
difficulty	1–10	Current learning difficulty
step	0–20	Current episode step

The environment also maintains reward and termination information through its interaction lifecycle.

5.2 Action Space

The environment provides five discrete educational interventions.

A = {aₜₑₐcₕ, a_qᵤᵢ𝓏, aᵣₑᵥᵢₛₑ, aᵢₙcᵣₑₐₛₑ, a_dₑcᵣₑₐₛₑ}

Action	Description	Purpose
teach	Introduces new learning material	Knowledge acquisition
quiz	Tests student understanding	Knowledge assessment
revise	Reinforces existing knowledge	Knowledge retention
increase_difficulty	Increases difficulty by one level	Progressive challenge
decrease_difficulty	Decreases difficulty by one level	Reduce excessive challenge

Difficulty is constrained within the following interval:

1 ≤ Dₜ ≤ 10

5.3 Environment Dynamics

The environment simulates student learning through mathematical transitions.

The following equations describe the current implementation.

A. Teaching Dynamics

When the agent selects teach, knowledge gain depends on current attention.

ΔKₜₑₐcₕ = U(2, 5) × Aₜ

Knowledge before forgetting:

K′ = Kₜ + ΔKₜₑₐcₕ

Fatigue increases:

F′ = Fₜ + 0.05

Interpretation: Students with higher attention gain more knowledge from the same teaching intervention.

B. Quiz Dynamics

The probability of successfully answering a quiz is proportional to current knowledge.

P(success) = Kₜ / 100

If the quiz is successful:

K′ = Kₜ + U(1, 3)

Otherwise:

K′ = Kₜ − U(0.5, 1.5)

Fatigue increases:

F′ = Fₜ + 0.08

Interpretation: A student with higher knowledge has a greater probability of answering correctly.

C. Revision Dynamics

Revision reinforces existing knowledge.

K′ = Kₜ + U(1, 2)

Fatigue increases:

F′ = Fₜ + 0.03

Interpretation: Revision provides a smaller knowledge improvement with a lower fatigue increase than teaching or quizzes in the current simulation.

D. Fatigue Dynamics

Fatigue is capped at 1.0.

Fₜ₊₁ = min(1, F′)

Attention is reduced according to updated fatigue.

A′ = max(0.3, Aₜ − 0.1 × Fₜ₊₁)

Interpretation: Higher accumulated fatigue reduces the student's ability to concentrate.

E. Attention Fluctuations

Attention also experiences random fluctuations.

εₜ ~ Uniform(−0.05, 0.05)

The updated attention becomes:

Aₜ₊₁ = clip(A′ + εₜ, 0.3, 1.0)

The clipping function ensures that attention remains within its allowed range.

F. Knowledge Forgetting

The forgetting factor depends on the updated attention level.

λₜ = 0.01 × (1 − Aₜ₊₁)

Knowledge after forgetting:

Kₜ₊₁ = clip(K′ × (1 − λₜ), 0, 100)

Interpretation: Lower attention leads to a higher forgetting rate, while higher attention helps preserve knowledge.

G. Difficulty Adaptation

Difficulty changes in discrete increments.

For increasing difficulty:

Dₜ₊₁ = min(10, Dₜ + 1)

For decreasing difficulty:

Dₜ₊₁ = max(1, Dₜ − 1)

The difficulty actions do not directly increase knowledge or fatigue. Their effect is reflected in reward calculation.

Transition Order

The environment processes each action in the following order:

1. Apply the selected teaching action.
2. Update fatigue.
3. Update attention based on fatigue.
4. Apply random attention fluctuations.
5. Apply knowledge forgetting.
6. Calculate reward.
7. Increment the episode step.
8. Check episode termination.

This order determines the final student state and reward after every interaction.

5.4 Reward Function

The reward function evaluates whether the selected intervention improves learning while maintaining an appropriate difficulty level.

The current implementation uses five components.

A. Knowledge Gain

The primary positive reward comes from knowledge improvement.

ΔKₜ = Kₜ₊₁ − Kₜ

Rₗₑₐᵣₙᵢₙg = 1.5 × ΔKₜ

B. Difficulty Alignment

The environment estimates optimal difficulty using current knowledge.

Dₒₚₜᵢₘₐₗ = Kₜ₊₁ / 10

The difference between actual and estimated difficulty is:

Gₜ = |Dₜ − Dₒₚₜᵢₘₐₗ|

Difficulty penalty:

P_difficulty = −0.1 × Gₜ

C. Fatigue Penalty

Higher fatigue produces a negative reward.

P_fatigue = −0.2 × Fₜ₊₁

D. Boredom Penalty

A penalty is applied when difficulty is more than two levels below the estimated optimal difficulty.

P_boredom = −0.1, when Dₜ < Dₒₚₜᵢₘₐₗ − 2.

Otherwise:

P_boredom = 0

E. Frustration Penalty

A penalty is applied when difficulty is more than two levels above the estimated optimal difficulty.

P_frustration = −0.1, when Dₜ > Dₒₚₜᵢₘₐₗ + 2.

Otherwise:

P_frustration = 0

Complete Reward Equation

The complete reward calculation is:

Rₜ = Rₗₑₐᵣₙᵢₙg + P_difficulty + P_fatigue + P_boredom + P_frustration

Expanded:

Rₜ = 1.5 × ΔKₜ − 0.1 × Gₜ − 0.2 × Fₜ₊₁ − 0.1 × I_boredom − 0.1 × I_frustration

Here, the indicator variables are:

• I_boredom = 1 when the boredom condition is satisfied; otherwise 0.
• I_frustration = 1 when the frustration condition is satisfied; otherwise 0.

Important: Reward is calculated after the student dynamics have been updated. Knowledge gain therefore includes the effect of forgetting during the same step.

The reward is not normalized to a fixed 0–1 range in the current implementation.

5.5 Episode Termination

The current environment uses a fixed episode length.

Tₘₐₓ = 20

An episode terminates when:

done = True, when step ≥ 20

The environment returns the final student observation when the maximum number of steps is reached.

---

6. Student Profiles

CogniStep currently provides three predefined student scenarios.

Each profile initializes the simulation with different learning conditions.

Parameter	Strong Student	Average Student	Weak Student
Initial Knowledge	10–20	20–40	10–20
Initial Attention	0.8–1.0	0.6–1.0	0.3–0.5
Initial Fatigue	0.0	0.0	0.5
Initial Difficulty	1	3	3

Strong Student

The strong student starts with relatively high attention and no accumulated fatigue.

The objective is to explore teaching strategies that improve knowledge while progressively increasing the learning challenge.

Average Student

The average student starts with moderate knowledge and variable attention.

The agent needs to balance teaching, revision, assessment, and difficulty adaptation.

Weak Student

The weak student starts with lower attention and higher fatigue.

The agent needs to explore strategies that maintain learning progress without excessive cognitive exhaustion.

Selecting a Profile

The environment accepts a task_name parameter.

env = EdTechEnvironment(
    task_name="strong_student",
    seed=42
)

Available profiles:

"strong_student"
"average_student"
"weak_student"

An unrecognized task name currently falls back to the average student configuration.

---

7. Installation

Prerequisites

• Python 3.10 or newer, subject to dependency compatibility.
• Docker.
• Git.
• OpenEnv-compatible Python dependencies.

Clone the Repository

git clone https://github.com/semanticsumit/CogniStep.git

cd CogniStep

Build Docker Image

From the repository root:

docker build \
  -t cognistep_env:latest \
  -f cognistep_env/server/Dockerfile .

Verify that the image has been created:

docker images cognistep_env

For local development, install the dependencies declared by the project before importing the environment modules.

---

8. Quick Start

The following example demonstrates direct interaction with the simulation.

from cognistep_env.server.environment import EdTechEnvironment
from cognistep_env.models import EdTechAction

# Initialize the environment
env = EdTechEnvironment(
    task_name="average_student",
    seed=42
)

# Reset the environment
observation = env.reset()

print("Initial Student State")
print("Knowledge:", observation.knowledge)
print("Attention:", observation.attention)
print("Fatigue:", observation.fatigue)
print("Difficulty:", observation.difficulty)

# Define teaching interventions
actions = [
    "teach",
    "quiz",
    "revise",
    "teach",
    "increase_difficulty"
]

for action_type in actions:

    if env.done:
        break

    observation = env.step(
        EdTechAction(action_type=action_type)
    )

    print(f"\nAction: {action_type}")

    print("Knowledge:", observation.knowledge)
    print("Attention:", observation.attention)
    print("Fatigue:", observation.fatigue)
    print("Difficulty:", observation.difficulty)
    print("Step:", observation.step)
    print("Done:", env.done)

This example demonstrates how an external decision-making process can interact with the student simulation.

For complete OpenEnv client/server interaction, use the client interface supplied by the installed OpenEnv package.

---

9. Environment API

The environment provides a sequential interaction interface.

Reset

Initializes a new episode.

observation = env.reset()

The environment initializes the student state using the selected profile and configured random seed.

Step

Executes an educational intervention.

action = EdTechAction(
    action_type="teach"
)

observation = env.step(action)

The environment processes the action and returns an updated observation.

Close

If using a client or server connection, close the connection through the corresponding OpenEnv client lifecycle.

env.close()

Use the actual environment or client API appropriate to the selected integration.

---

10. Reinforcement Learning Integration

CogniStep is designed to be algorithm-agnostic.

Different reinforcement learning algorithms can interact with the same environment without changing the underlying student simulation.

Potential Algorithms

Algorithm	Learning Approach	Potential Application
PPO	Policy Gradient / Actor-Critic	Adaptive teaching policies
DQN	Value-Based Learning	Discrete teaching actions
A2C	Advantage Actor-Critic	Sequential decision-making
REINFORCE	Policy Gradient	Episodic learning
Contextual Bandits	Reward-Based Selection	Choosing interventions based on student state

These are proposed integrations, not currently included training implementations.

Recommended: PPO

PPO is a promising candidate because the environment has a small discrete action space and continuous observation variables.

A potential architecture:

          Student Observation
                   |
                   v
          +------------------+
          | Feature Encoder  |
          +------------------+
                   |
                   v
          +------------------+
          |    PPO Actor     |
          |                  |
          | Action Selection |
          +------------------+
                   |
                   v
             Selected Action
                   |
                   v
          CogniStep Environment
                   |
                   v
           Reward + Next State
                   |
                   v
          +------------------+
          |   PPO Critic     |
          | Value Estimation |
          +------------------+
                   |
                   v
           Policy Optimization
                   |
                   +----> Repeat

The Actor selects teaching actions, while the Critic estimates expected future rewards.

PPO can optimize the policy using collected environment interactions.

LLM-Based Agents

CogniStep can also be connected to LLM-based decision-making agents.

An LLM can interpret student observations and select an educational intervention.

A hybrid architecture could combine:

• LLMs for educational reasoning and content generation.
• RL policies for optimizing teaching interventions.
• CogniStep for student simulation and reward feedback.

This makes it possible to compare conventional reinforcement learning agents with LLM-based and hybrid approaches.

---

11. Evaluation and Benchmarking

The goal of evaluation is to determine whether an agent can consistently improve student learning outcomes.

Performance should be measured using more than cumulative reward.

Recommended Evaluation Metrics

Metric	Purpose
Mean Episode Reward	Overall agent performance
Final Knowledge	Knowledge at episode termination
Knowledge Gain	Improvement from initial knowledge
Average Attention	Sustained concentration
Average Fatigue	Cognitive fatigue across an episode
Retention	Preservation of acquired knowledge
Difficulty Alignment	Appropriateness of challenge
Episode Length	Number of interactions

Recommended Baseline Agents

1. Random Agent

Selects an action randomly from the available action space.

Purpose: Establishes a simple performance reference.

2. Rule-Based Agent

Uses predefined conditions to select interventions.

Example:

if fatigue > 0.7:
    action = "revise"

elif attention < 0.4:
    action = "decrease_difficulty"

elif knowledge < 50:
    action = "teach"

else:
    action = "quiz"

This is an illustrative baseline policy, not a bundled implementation.

3. RL Agent

Learns an intervention policy through repeated interactions and reward feedback.

Purpose: Evaluates whether policy optimization can outperform fixed decision-making strategies.

Recommended Experimental Protocol

For reliable evaluation:

• Run multiple independent episodes.
• Use multiple random seeds.
• Report mean and standard deviation.
• Evaluate all student profiles.
• Compare against random and rule-based policies.
• Plot training reward curves.
• Report final knowledge alongside cumulative reward.

No independently validated benchmark results are currently published in this repository.

Numerical performance claims should only be added after running reproducible experiments.

---

12. Current Limitations

CogniStep is an experimental environment.

Its current simulation is intentionally simplified and should not be interpreted as a fully validated cognitive model of human learning.

Understanding these limitations is important when using the environment for research.

12.1 Simplified Learning Dynamics

The current knowledge model uses random increments for teaching and revision.

Real learning depends on additional factors such as:

• Prior knowledge.
• Concept complexity.
• Instructional quality.
• Individual learning differences.
• Previous learning experiences.

Potential improvement: Introduce concept-level mastery, more realistic learning curves, and configurable learning rates.

12.2 Simplified Forgetting Model

The current forgetting mechanism uses a fixed attention-dependent decay factor.

It does not explicitly model elapsed real time, spaced repetition, or long-term memory consolidation.

Potential improvement: Explore Ebbinghaus-inspired forgetting curves and spaced repetition models.

12.3 No Fatigue Recovery

Fatigue currently accumulates through learning activities and is capped at 1.0.

There is no independent recovery mechanism.

Potential improvement: Introduce rest, recovery, and time-dependent fatigue decay.

12.4 Limited Student Diversity

Only three predefined student profiles are currently available.

They do not represent the full diversity of individual learning behavior.

Potential improvement: Introduce configurable parameters for learning speed, attention stability, fatigue sensitivity, forgetting rate, and difficulty tolerance.

12.5 Simplified Difficulty Alignment

The current optimal difficulty estimate is calculated using knowledge divided by ten.

This is an experimental starting point rather than a validated pedagogical model.

Potential improvement: Use assessment accuracy, concept mastery, and student performance history to estimate appropriate difficulty.

12.6 Fixed Episode Length

The current episode length is limited to 20 steps.

Potential improvement: Support configurable episode lengths and additional termination conditions.

12.7 Limited Reproducibility Controls

The current implementation reinitializes its random generator using the configured seed during every reset.

Consequently, repeated resets with the same environment instance reproduce the same initial state and random sequence.

Potential improvement: Separate initial reproducibility from episode-level randomization and expose explicit seed controls.

12.8 Limited State Representation

The current observation exposes knowledge, attention, fatigue, difficulty, and step.

Some useful historical information is not explicitly exposed to the agent.

For example:

• Previous knowledge.
• Knowledge gain.
• Recent action history.
• Assessment history.
• Learning progress over multiple steps.

Potential improvement: Introduce historical observation features or explicitly investigate partially observable decision-making.

12.9 No Integrated RL Training Pipeline

The repository currently focuses on environment simulation and server integration.

It does not include complete PPO or DQN training implementations, trained checkpoints, or a validated benchmark suite.

Potential improvement: Build separate training and evaluation modules without coupling policy optimization to the environment engine.

12.10 Simplified Reward Design

The current reward is primarily driven by knowledge gain and penalties.

It does not explicitly optimize long-term retention, assessment reliability, or student engagement.

Potential improvement: Investigate alternative reward formulations and compare their effects on learned teaching strategies.

---

13. Future Roadmap

The following roadmap describes possible directions for evolving CogniStep into a more comprehensive adaptive learning research platform.

Phase 1 — Environment Improvements

• Configurable student parameters.
• Independent episode randomization.
• Configurable episode length.
• Fatigue recovery mechanism.
• Improved forgetting dynamics.
• Concept-level knowledge modeling.
• Comprehensive environment tests.

Phase 2 — Reinforcement Learning

• Random baseline agent.
• Rule-based baseline agent.
• PPO training integration.
• DQN training integration.
• Model checkpoint management.
• Training configuration support.
• Reproducible evaluation pipeline.

Phase 3 — Advanced Student Modeling

• Individual learning-speed parameters.
• Long-term memory simulation.
• Adaptive difficulty estimation.
• Student engagement modeling.
• Learning outcome prediction.
• Partially observable student-state experiments.

Phase 4 — Intelligent Tutoring Systems

• LLM-based teaching agents.
• Hybrid LLM + RL architecture.
• Dynamic educational content generation.
• Personalized learning strategies.
• Multi-concept learning scenarios.
• Validation using real student data.

Phase 5 — Research and Evaluation Platform

• Standardized benchmark scenarios.
• Agent performance comparisons.
• Learning curve visualization.
• Reward analysis dashboard.
• Cross-profile policy evaluation.
• Research experiment documentation.

---

14. Project Structure

CogniStep/
│
└── cognistep_env/
    │
    ├── README.md
    ├── openenv.yaml
    ├── __init__.py
    ├── models.py
    │
    └── server/
        │
        ├── __init__.py
        ├── environment.py
        ├── app.py
        └── Dockerfile

Core Components

File	Responsibility
models.py	Defines actions, observations, and internal state models
server/environment.py	Implements student initialization, transitions, and reward calculation
server/app.py	Provides the FastAPI environment server
server/Dockerfile	Defines containerized deployment
openenv.yaml	OpenEnv environment configuration
README.md	Project documentation

---

15. Deployment

CogniStep supports Docker-based deployment to Hugging Face Spaces using OpenEnv tooling.

Prerequisites

• Hugging Face account.
• OpenEnv CLI installed.
• Hugging Face authentication configured.
• Valid OpenEnv manifest.

Deploy

Navigate to the directory containing openenv.yaml:

cd cognistep_env

Run:

openenv push

Deploy to a specific namespace:

openenv push --namespace my-org --private

Or specify a repository:

openenv push --repo-id my-org/cognistep_env

After successful deployment, the Space will be available at:

https://huggingface.co/spaces/<repo-id>

Refer to OpenEnv CLI documentation for supported deployment options and configuration.

---

16. Contributing

Contributions, experiments, and research ideas are welcome.

Potential areas for contribution include:

• Improving student learning dynamics.
• Developing more realistic forgetting models.
• Designing alternative reward functions.
• Implementing reinforcement learning agents.
• Adding new student profiles.
• Improving evaluation methodologies.
• Extending OpenEnv integration.

Contribution Workflow

1. Fork the repository.
2. Create a feature branch.
3. Implement your changes.
4. Add appropriate tests.
5. Submit a pull request describing your contribution.

For major architectural changes, consider opening an issue before implementation.

---

17. License

Refer to the repository's LICENSE file for licensing and usage terms.

---

CogniStep

Every student learns differently. Teaching should adapt accordingly.

An experimental foundation for intelligent and adaptive educational agents.

Explore the GitHub Repository