Metadata-Version: 2.4
Name: plato-neural
Version: 0.3.0
Summary: PLATO Neural Inference Engine — fine-tuned LLM for PLATO knowledge scoring, generation, and Q&A
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.36
Requires-Dist: peft>=0.7
Provides-Extra: lora
Requires-Dist: peft>=0.7; extra == "lora"
Provides-Extra: server
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: datasets; extra == "dev"
Requires-Dist: peft>=0.7; extra == "dev"

# PLATO Neural v0.2.0

Neural inference engine for the PLATO knowledge network. Fine-tuned Qwen2.5-0.5B for tile scoring, Q&A, gap detection, and tile generation.

## Install

```bash
pip install plato-neural
```

## CLI Usage

```bash
# Ask a question
plato-neural ask "What is constraint theory?"

# Score a tile (neural — requires GPU)
plato-neural score -q "What is a tile?" -a "A 256-byte knowledge unit..."

# Score a tile (heuristic — no GPU needed)
plato-neural score -q "What is a tile?" -a "A knowledge unit..." --heuristic

# Check model health
plato-neural health

# Start REST API
plato-neural serve --port 5050
```

## REST API

```bash
# Health
curl http://localhost:5050/health

# Ask
curl -X POST http://localhost:5050/ask -H 'Content-Type: application/json' \
  -d '{"question": "What is constraint theory?"}'

# Score
curl -X POST http://localhost:5050/score -H 'Content-Type: application/json' \
  -d '{"question": "...", "answer": "..."}'

# Batch score
curl -X POST http://localhost:5050/batch_score -H 'Content-Type: application/json' \
  -d '{"tiles": [{"question": "...", "answer": "..."}]}'

# Generate tile
curl -X POST http://localhost:5050/generate_tile -H 'Content-Type: application/json' \
  -d '{"room": "ct"}'

# Find knowledge gaps
curl -X POST http://localhost:5050/find_gaps -H 'Content-Type: application/json' \
  -d '{"tiles": [...], "threshold": 50}'
```

## Python API

```python
from plato_neural import PlatoBrain

brain = PlatoBrain("Qwen/Qwen2.5-0.5B")

# Q&A
result = brain.ask("What is constraint theory?")
print(result["answer"])

# Score tiles
score = brain.score("What is a tile?", "A 256-byte knowledge unit...")
print(f"PPL: {score['perplexity']}, Tier: {score['tier']}")

# Generate new tiles
tile = brain.generate_tile("ct")
print(tile["question"], tile["answer"])

# Find gaps in knowledge
gaps = brain.find_gaps(tiles, threshold=50)
```

## Performance (RTX 4050, exp8 LoRA)

| Metric | Value |
|--------|-------|
| Avg perplexity | ~5-7 |
| Tile recognition | ~98% |
| Confidence | 0.97+ |
| Generation speed | 70+ tok/s |
| VRAM | ~1.0GB (bf16), ~545MB (INT8) |

## Changelog

### v0.2.0
- REST API server with 6 endpoints
- Heuristic scorer (no GPU required)
- CLI with ask/score/health/serve commands
- PlatoBrain class with ask/score/generate/batch_score/find_gaps
- PlatoScorer class for lightweight heuristic scoring

### v0.1.0
- Initial release: PlatoBrain + PlatoScorer
