# CPUAI Prototype Docs

## Goal
Build a lightweight, framework-free PHP semantic prototype that runs on CPU and uses geometric context retrieval instead of a full transformer stack.

## Current status
- Core semantic engine implemented in plain PHP.
- Retrieval endpoint available via public/api.php.
- Interactive UI available via public/ui.php.
- Manual training form available via public/train.php.
- One-click training from uploaded files via public/train_from_file.php.
- Upload and text extraction for .txt and .pdf files via public/upload.php.
- Article drafting via public/article.php.
- Local Ollama-based synthetic training support via php train_ollama.php or train_ollama.bat.

## Main entry points
- UI: http://localhost/cpuai/public/ui.php
- API: http://localhost/cpuai/public/api.php?text=hot%20cold%20dog
- Manual training: http://localhost/cpuai/public/train.php
- Upload content: http://localhost/cpuai/public/upload.php
- One-click training: http://localhost/cpuai/public/train_from_file.php
- Article draft: http://localhost/cpuai/public/article.php?text=hot%20cold%20dog&title=Sample%20Article

## Architecture
- app/bootstrap.php loads shared classes and dependencies.
- core/TextProcessor.php cleans and tokenizes input.
- core/SemanticSpace.php stores embeddings and semantic relations.
- core/ContextState.php tracks a fixed-size semantic context vector.
- core/Router.php scores tokens against the current context.
- core/Retriever.php returns nearest related concepts.
- core/PdfExtractor.php extracts text from uploaded files when possible.
- core/ArticleGenerator.php builds simple article-style output from semantic chunks.
- data/*.json stores embeddings, relations, examples, state, and training reports.

## How it works
1. Text is cleaned and tokenized.
2. Tokens map to stored vectors.
3. The context state is updated as each token is processed.
4. The router scores how strongly the token fits the active context.
5. Retrieval returns related concepts and the current semantic state.

## How to use it
- Open the UI for interactive retrieval.
- Use the API endpoint for raw JSON responses.
- Upload files to inspect extracted text.
- Use the training pages to add concepts manually or from uploaded files.
- Run Ollama training to generate synthetic textbook-style examples and enrich the semantic space.

## Training options
- Manual form: public/train.php
- File-based training: public/train_from_file.php
- Ollama training: php train_ollama.php or train_ollama.bat
- Direct JSON editing: data/embeddings.json, data/relations.json, and data/examples.json

## Notes
- No frameworks and no Composer are used.
- The project is designed to stay simple, inspectable, and CPU-friendly.
- These docs are updated as features change.