Metadata-Version: 2.4
Name: kernelbot-ml
Version: 1.0.3
Summary: Pure Python ML chatbot with token-based learning. Zero dependencies!
Home-page: https://github.com/Endyboii/Kernelbotv.5
Author: CraftKernel (Endyboii)
Author-email: 
License: MIT
Project-URL: Homepage, https://github.com/Endyboii/Kernelbotv.5
Project-URL: Repository, https://github.com/Endyboii/Kernelbotv.5.git
Project-URL: Bug Tracker, https://github.com/Endyboii/Kernelbotv.5/issues
Project-URL: Documentation, https://github.com/Endyboii/Kernelbotv.5#readme
Keywords: chatbot,ml,learning,nlp,token-based,llm,ai
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# kernelbot-ml

**Pure Python machine learning learning engine.** Zero external dependencies. Fast. Lightweight.

Perfect for:
- 🧠 Learning ML fundamentals
- 📚 Token-based text learning
- ⚡ Real-time pattern learning
- 🔄 Persistent knowledge storage

## Installation

```bash
pip install kernelbot-ml
```

## Quick Start

```python
from kernelbot_ml import LearningChatbot

# Create a bot
bot = LearningChatbot("MyBot")

# Load a dataset (optional)
bot.load_dataset("greetings")  # or custom JSON file

# Chat
response = bot.chat("Hello!")
print(response['response'])

# Teach the bot
bot.teach("What is AI?", "AI is artificial intelligence")

# Get statistics
stats = bot.get_statistics()
print(f"Fluency: {stats['fluency_level']}")
```

## How It Works

### LLM-Style Learning
1. **Tokenization** - Breaks text into tokens
2. **Vocabulary Building** - Creates token → ID mapping
3. **N-Gram Learning** - Learns bigrams and trigrams (context patterns)
4. **Probability Distribution** - Predicts next token based on context
5. **Temperature Sampling** - Generates varied responses

### Token-Based Generation
- Encodes input into token IDs
- Maintains a context window (20 tokens default)
- Predicts next tokens based on learned patterns
- Uses temperature/top-k/top-p sampling for variety

## Features

✨ **Core Learning**
- 🧠 LLM-Style token-based learning (like GPT/Gemini)
- 💾 Auto-save knowledge to JSON
- 📊 Statistics tracking (fluency level, patterns learned)
- 🎓 6 fluency levels: untrained → eloquent

📚 **Dataset Management**
- Load pre-built datasets (greetings, technology, FAQ)
- Create custom JSON datasets
- Merge multiple datasets
- Export/import bot state

⚙️ **Pure Python**
- ✅ No external ML dependencies
- ✅ Lightweight (~50KB)
- ✅ Works everywhere Python runs
- ✅ Easy to extend

## API Reference

### LearningChatbot

```python
from kernelbot_ml import LearningChatbot

bot = LearningChatbot("BotName")
```

**Methods:**
- `chat(user_input)` - Get a response
- `teach(question, answer, category="general")` - Teach the bot
- `load_dataset(filepath)` - Load JSON dataset
- `save_knowledge(filename)` - Save learned knowledge
- `train_custom(training_data)` - Train on list of Q&A pairs
- `get_statistics()` - Get bot stats (patterns, fluency, etc)
- `export_full_state(filename)` - Export everything
- `import_full_state(filepath)` - Import previous state

### NLPEngine

```python
from kernelbot_ml.core import NLPEngine

engine = NLPEngine()
```

**Methods:**
- `add_knowledge(question, answer, category)` - Add to knowledge base
- `train(training_data)` - Train engine
- `generate_response(user_input)` - Generate response
- `learn_from_conversation(input, answer)` - Learn from interaction
- `find_similar(query, top_k)` - Find similar documents

### DatasetManager

```python
from kernelbot_ml.datasets import DatasetManager

manager = DatasetManager()
```

**Methods:**
- `export_dataset(data, filename)` - Export to JSON
- `import_dataset(filepath)` - Import from JSON
- `list_datasets()` - List all datasets
- `merge_datasets(set1, set2)` - Merge two datasets

## Dataset Format

Create custom datasets as JSON files:

```json
{
  "metadata": {
    "created": "2026-03-07",
    "version": "1.0",
    "description": "Your dataset description"
  },
  "data": [
    {
      "input": "hello",
      "output": "Hi there! How can I help?"
    },
    {
      "input": "what is AI",
      "output": "AI is artificial intelligence"
    }
  ]
}
```

Then load it:
```python
bot.load_dataset("path/to/your_dataset.json")
```

## Fluency Levels

Bots progress through 6 fluency levels as they learn:

| Level | Tokens Seen | Description |
|-------|-------------|-------------|
| untrained | 0 | No training yet |
| babbling | <100 | Just starting |
| toddler | <500 | Learning basics |
| child | <2000 | Making progress |
| teenager | <10000 | Getting good |
| eloquent | 10000+ | Fully trained |

## Example: Custom Training

```python
from kernelbot_ml import LearningChatbot

bot = LearningChatbot("TechBot")

# Train on custom data
training_data = [
    {"input": "what is python", "output": "Python is a programming language"},
    {"input": "what is machine learning", "output": "ML allows computers to learn from data"},
]

bot.train_custom(training_data)

# Chat
response = bot.chat("What is Python?")
print(response['response'])
# Output: "Python is a programming language"

# Get stats
stats = bot.get_statistics()
print(stats)
# {'fluency_level': 'child', 'patterns_learned': 2, ...}
```

## Example: Export & Import

```python
# Save the bot's learned knowledge
bot.save_knowledge("my_bot_knowledge")

# Later, create a new bot and import
bot2 = LearningChatbot("MyBot2")
bot2.import_full_state("my_bot_knowledge.json")
```

## Module Structure

```
kernelbot_ml/
├── core/
│   ├── nlp_engine.py        # NLP engine with learning
│   └── chatbot.py           # Main chatbot class
├── datasets/
│   ├── dataset_manager.py   # Import/export functionality
│   ├── greetings.json       # Example dataset
│   ├── technology.json      # Example dataset
│   └── faq.json             # Example dataset
└── utils/
    └── ui.py                # Terminal UI utilities
```

## Requirements

- Python 3.7+
- **Zero external dependencies!** Uses only Python standard library

## Performance

- ⚡ Instant responses (no model downloads)
- 💾 Low memory usage (pure Python)
- 📦 Tiny package size (~50KB)
- 🔄 Real-time learning

## Testing

```bash
python -m pytest tests/
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Submit a pull request

## License

MIT License - feel free to use and modify!

## Acknowledgments

Educational project demonstrating:
- Natural Language Processing basics
- Machine Learning fundamentals
- Pattern recognition algorithms
- Python OOP principles
- Package distribution

---

Made with ❤️ by CraftKernel (Endyboii)

Questions? [Create an issue](https://github.com/Endyboii/Kernelbotv.5/issues) or check the [main repository](https://github.com/Endyboii/Kernelbotv.5)
