# CPUAI Prototype Manual

## Quick start
1. Place the project in a PHP-enabled web root.
2. Open the main UI at http://localhost/cpuai/public/ui.php.
3. Try a retrieval query such as http://localhost/cpuai/public/api.php?text=hot%20cold%20dog.
4. Use http://localhost/cpuai/public/train.php to add new concepts manually.
5. Use http://localhost/cpuai/public/upload.php to upload .txt or .pdf files.
6. Use http://localhost/cpuai/public/train_from_file.php to train from an uploaded file with one click.
7. Use http://localhost/cpuai/public/article.php?text=hot%20cold%20dog&title=Sample%20Article to create a simple article draft.

## Main pages
- public/ui.php: interactive retrieval UI.
- public/api.php: JSON API endpoint.
- public/train.php: manual training form.
- public/upload.php: upload and text extraction page.
- public/train_from_file.php: one-click file-based training.
- public/article.php: article generation endpoint.

## Files
- app/config.php: shared configuration constants.
- app/bootstrap.php: loads all classes and dependencies.
- core/TextProcessor.php: text cleaning and tokenization.
- core/SemanticSpace.php: embedding and relation management.
- core/ContextState.php: fixed-size context state.
- core/Router.php: context-aware routing.
- core/Retriever.php: similarity-based retrieval.
- core/PdfExtractor.php: text extraction from uploaded files.
- core/ArticleGenerator.php: simple article drafting.
- data/*.json: seed data, training data, and runtime state.

## Training
You can teach the system in several ways.

### Manual form
Use public/train.php to add a term, relation, and vector directly.

### File-based training
Upload a text or PDF file, then use public/train_from_file.php to train the semantic space with one mouse click.

### Automated Ollama training
Run train_ollama.bat or execute php train_ollama.php. This calls the local Ollama endpoint and asks phi4-mini to produce synthetic textbook-style examples, then updates the embedding store.

### JSON editing
Edit the JSON files directly to teach the system new concepts.

#### Add a term
Add a new entry to data/embeddings.json.

Example:
```json
"river": [0.3, 0.2, 0.7, 0.1, 0.1, 0.0, 0.0, 0.1]
```

#### Add a relation
Add a new relation entry to data/relations.json.

Example:
```json
"river": ["water"]
```

#### Add an example
Add an example to data/examples.json.

Example:
```json
{
  "input": "river",
  "target": "water",
  "context": "water"
}
```

## Retrieval
Send text with a query parameter such as:
- ?text=hot dog
- ?text=fast slow
- ?text=light dark

The server returns the processed tokens, route scores, related terms, and the current context vector.

## Configuration
The main behavior is controlled from app/config.php.

- CPUAI_DIMENSIONS: sets the size of each semantic vector.
- CPUAI_MIN_TOKEN_LENGTH: ignores very short tokens so the system focuses on meaningful words.
- CPUAI_CONTEXT_WEIGHT: controls how strongly a token influences the current context state.
- CPUAI_ENABLE_CONTEXT_UPDATES: turns context updates on or off during retrieval.
- CPUAI_TRAINING_RATE: sets the learning rate for general training examples.
- CPUAI_FILE_TRAINING_RATE: sets the stronger learning rate used when training from uploaded files.
- CPUAI_EXAMPLE_LIMIT: caps how many examples are produced from a single text source.
- CPUAI_MIN_EXAMPLE_COUNT: prevents weak training from very short input.
- CPUAI_ENABLE_FILE_ARTIFACTS: creates a semantic artifact for each uploaded file.
- CPUAI_ENABLE_OLLAMA_ENRICHMENT: enables Ollama-based enrichment of the semantic space.

CPUAI_DIMENSIONS = 8

Sets the size of each semantic vector. Bigger values can hold more nuanced meaning, but also increase memory and compute.
CPUAI_MIN_TOKEN_LENGTH = 2

Filters out very short tokens so the system focuses on meaningful words instead of noise.
CPUAI_CONTEXT_WEIGHT = 0.6

Controls how strongly a token’s vector influences the current context state during retrieval. Higher values make the context change faster.
CPUAI_ENABLE_CONTEXT_UPDATES = true

Turns context accumulation on or off. When off, retrieval behaves more statically.
CPUAI_TRAINING_RATE = 0.2

Controls how aggressively general training examples update vectors. Higher values make training stronger and faster, but can also overreact.
CPUAI_FILE_TRAINING_RATE = 0.24

This is the stronger learning rate used when training from uploaded files, so file-based import has a larger effect than normal examples.
CPUAI_EXAMPLE_LIMIT = 64

Caps how many training examples are produced from a source text. This prevents overly large training runs.
CPUAI_MIN_EXAMPLE_COUNT = 6

Prevents weak or trivial training from very short text inputs. The system waits for enough tokens before building examples.
CPUAI_ENABLE_FILE_ARTIFACTS = true

Creates a semantic artifact for each uploaded file, so the file itself becomes part of the learned space rather than only its words.
CPUAI_ENABLE_OLLAMA_ENRICHMENT = true

Enables phi4-mini / Ollama-based enrichment of the semantic space after generated examples are produced.


Adjust these values when you want to make the system more conservative, more aggressive, or more focused on uploaded content.

## Article generation
Use public/article.php?text=hot%20cold%20dog&title=Sample%20Article to generate a simple article draft from chunked input.

## Notes
- No frameworks are used.
- No Composer is used.
- The system is designed to be simple, inspectable, and CPU-friendly.
- These pages and instructions are kept current as the prototype evolves.