skillforge-cli 0.1.1
AI-powered CLI tool for interactive, personalized learning experiences
Requires Python: >=3.12
Keywords: cli, learning, ai, education, interactive

<div align="center">

<img src="https://raw.githubusercontent.com/milank94/skillforge/main/assets/logo.png" alt="SkillForge Logo" width="400">

**AI-powered interactive learning CLI for developers**

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-354%20passing-brightgreen.svg)]()
[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Architecture](#architecture) • [Contributing](#contributing)

</div>

---

SkillForge helps developers learn new frameworks, tools, and technologies through hands-on practice in safe, simulated environments. Get personalized courses, step-by-step guidance, and real-time feedback—all from your terminal.

<div align="center">

![SkillForge Demo](https://raw.githubusercontent.com/milank94/skillforge/main/assets/demo.gif)

</div>

## Status

🚧 **Active Development** — Interactive learning sessions now available!

## Features

**AI-Powered Course Generation** — Uses Claude or GPT to create personalized curricula with intelligent caching

**Safe Command Simulation** — Practice shell, Python, git, Docker, and kubectl without risk to your system

**Intelligent Validation** — Pattern matching + LLM evaluation with progressive hints and feedback

**Progress Persistence** — Save and resume sessions at any time

**Rich Terminal UI** — Beautiful course overviews, progress indicators, and formatted output

### Intelligent Feedback

SkillForge provides helpful feedback whether you get it right or need another try:

![Validation Examples](https://raw.githubusercontent.com/milank94/skillforge/main/assets/validation.png)

## Installation

### Install from PyPI

```bash
pip install skillforge-cli
# or
pipx install skillforge-cli
```

Then set up your API key and start learning:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
skillforge learn "python basics"
```

### Development Setup

**Requirements**: Python 3.12 or higher

1. **Clone the repository**
   ```bash
   git clone https://github.com/milank94/skillforge.git
   cd skillforge
   ```

2. **Create a virtual environment**
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install in editable mode**
   ```bash
   pip install --upgrade pip
   pip install -e ".[dev]"
   ```

4. **Set up API key**
   ```bash
   export ANTHROPIC_API_KEY=sk-ant-...
   # or
   export OPENAI_API_KEY=sk-...
   ```

5. **Verify installation**
   ```bash
   skillforge --version
   skillforge --help
   ```

## Usage

### Generate a Course

```bash
# Start a learning session (uses Anthropic by default)
skillforge learn "pytorch basics"

# Specify difficulty and lesson count
skillforge learn "docker fundamentals" --difficulty intermediate --lessons 7

# Use OpenAI instead
skillforge learn "kubernetes" --provider openai

# Non-interactive mode (just display the course)
skillforge learn "git basics" --no-interactive
```

<details open>
<summary>📸 Example: Generated PyTorch Course</summary>

<br>

![Generated Course Example](https://raw.githubusercontent.com/milank94/skillforge/main/assets/pytorch_advanced.png)

</details>

### Resume & Progress

```bash
# List saved sessions
skillforge resume

# Resume a specific session (supports partial IDs)
skillforge resume abc123

# View progress without resuming
skillforge status abc123
```

<details open>
<summary>📸 Example: Resume Menu</summary>

<br>

![Resume Menu](https://raw.githubusercontent.com/milank94/skillforge/main/assets/resume.png)

</details>

### Cache Management

```bash
# View cache info
skillforge cache-info

# Clear cached courses
skillforge cache-clear
```

## Configuration

### Environment Variables

```bash
ANTHROPIC_API_KEY=sk-ant-...       # Anthropic API key
OPENAI_API_KEY=sk-...              # OpenAI API key
SKILLFORGE_LLM_PROVIDER=anthropic  # Default provider (anthropic or openai)
SKILLFORGE_MODEL=claude-sonnet-4-5-20250929  # Model to use
SKILLFORGE_TEMPERATURE=0.7         # Generation temperature
SKILLFORGE_DATA_DIR=~/.skillforge  # Data directory
```

## Development

### Running Tests
```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_simulator.py

# Run integration tests (requires API keys)
pytest -m integration
```

### Code Quality
```bash
# Format code
black skillforge/ tests/

# Lint code
ruff check skillforge/ tests/

# Type checking
mypy skillforge/
```

## Architecture

```
┌─────────────────────────────────────────────┐
│              CLI Interface                   │
│           (typer + rich)                     │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│           Course Generator                   │
│     (LLM-powered, hash-based caching)       │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│          Command Simulator                   │
│  (pattern matching + LLM fallback)          │
│  Virtual file system, shell, Python,        │
│  git, docker, kubectl simulation            │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────┴──────────────────────────┐
│          Exercise Validator                  │
│  (pattern matching + LLM evaluation)        │
│  Progressive hints, score feedback          │
└─────────────────────────────────────────────┘
```

## Roadmap

- [x] Phase 1: Basic package setup and CLI structure
- [x] Phase 2: Data models (Course, Lesson, Exercise, Progress)
- [x] Phase 3: LLM integration (course generator, simulator, validator)
- [x] Phase 4: Interactive learning sessions and progress tracking

## Project Structure

```
skillforge/
├── skillforge/              # Main package
│   ├── __init__.py          # Package initialization
│   ├── cli.py               # CLI interface (typer + rich)
│   ├── core/                # Core functionality
│   │   ├── course_generator.py  # LLM-based course creation
│   │   ├── session.py           # Interactive session manager
│   │   ├── simulator.py         # Command simulation engine
│   │   └── validator.py         # Exercise validation engine
│   ├── models/              # Pydantic data models
│   │   ├── course.py            # Course, Lesson, Exercise
│   │   ├── config.py            # AppConfig, LLMConfig
│   │   ├── enums.py             # Difficulty, LLMProvider, etc.
│   │   ├── progress.py          # Progress tracking
│   │   └── session.py           # Learning session
│   └── utils/               # Utilities
│       ├── llm_client.py        # Anthropic + OpenAI clients
│       ├── output.py            # Rich display helpers
│       └── serialization.py     # JSON serialization
├── tests/                   # 354 tests, 93% coverage
├── pyproject.toml           # Project configuration
├── README.md                # This file
└── CLAUDE.md                # Development guide
```

## Contributing

This is currently a learning project. Contributions and suggestions are welcome!

## License

MIT License - see LICENSE file for details

## Learn More

For detailed architecture and development guidelines, see [CLAUDE.md](CLAUDE.md).