Metadata-Version: 2.4
Name: PhantomReason
Version: 0.1.2
Summary: Symbolic AI reasoning engine built on PhantomTrace absence arithmetic. Trace-based memory, fact management, and semantic retrieval for standalone use or as an augmentation layer over LLMs.
Author: PhantomTrace Agent Maintainers
License-Expression: MIT
Project-URL: Homepage, https://github.com/phantomtrace/phantomreason
Project-URL: Documentation, https://github.com/phantomtrace/phantomreason#readme
Project-URL: Repository, https://github.com/phantomtrace/phantomreason
Project-URL: Issues, https://github.com/phantomtrace/phantomreason/issues
Keywords: phantomtrace,phantomreason,symbolic-ai,reasoning,memory,agent,absence-arithmetic,trace-vector,fact-store,llm-augmentation
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: absence-calculator>=0.5.0
Dynamic: license-file

# PhantomReason

A symbolic AI reasoning engine built on [PhantomTrace](https://pypi.org/project/phantomtrace/) absence arithmetic.

PhantomReason is not a neural network. It represents knowledge as sparse binary vectors where each dimension is either *present* or *absent* -- the two fundamental states of PhantomTrace arithmetic. Learning happens by toggling these states through the same operations that define the algebra: `combine`, `compare`, `add`, `erase`, and `toggle`.

The result is a lightweight symbolic system that can store facts, answer questions, parse sentence structure, and generate constrained text -- all without gradient descent, matrix multiplication, or floating-point weights.

## Why This Exists

Large language models are powerful but opaque. They hallucinate, forget instructions, and offer no mechanism to inspect *why* they produced a given answer.

PhantomReason takes a different approach:

- **Every fact has a traceable strength** stored as a PhantomTrace number. You can inspect it, reinforce it with `add`, weaken it with `erase`, and watch it decay over time.
- **Predictions are distance-based.** The model ranks candidates by how close their trace vectors are to the current context. The scoring is transparent and deterministic.
- **Contradictions are resolved symbolically.** When a new fact conflicts with an old one, the old fact's strength is erased rather than silently overwritten.
- **Memory is explicit.** Episodes, facts, and symbols each have their own trace store with named banks. Nothing is hidden in a billion-parameter matrix.

This makes PhantomReason suitable as a standalone symbolic reasoner for constrained domains, or as an **augmentation layer** that can sit alongside an LLM to provide grounded fact memory, symbolic confidence tracking, and interpretable retrieval.

## Installation

```bash
pip install phantomreason
```

Requires Python 3.11+ and [`PhantomTrace`](https://pypi.org/project/phantomtrace/) (installed automatically).

## Performance

Initial model setup involves computing sparse trace vectors for the vocabulary and training corpus. On a typical machine:

| Operation | Time |
|-----------|------|
| Import + model init (dim=512) | ~1-2 seconds |
| Training on a few sentences | ~30-40 seconds |
| Subsequent startup with persisted state | ~3-5 seconds |
| Individual predictions | <1 second (warm cache) |
| `route_prompt` queries | 0.1-4 seconds |

The first run is the slowest because trace vectors must be computed for every word in the training data. After the model saves its state, restarts are fast because the vectors are loaded from disk rather than recomputed.

## Quick Start

```python
from phantomreason import PhantomLanguageModel

model = PhantomLanguageModel(dim=512, sparsity=47)

model.train_on_text(
    "aurora paints dawn softly. chefs simmer herbs slowly. "
    "gardeners water orchids gently.",
    epochs=1,
)

model.register_fact("chefs", "simmer", ["herbs", "slowly"])
model.register_fact("gardeners", "water", ["orchids", "gently"])

routed = model.route_prompt("what do chefs simmer?")
print(routed["fact_answer"])  # "herbs slowly"
print(routed["sample"])       # "chefs simmer herbs slowly."

prediction = model.predict_next(model.tokenize("aurora paints"))
print(prediction)  # "dawn"
```

**Note on fact recall:** `route_prompt` matches the question's predicate against stored fact predicates. The predicate in the question must match the stored form exactly (e.g., ask "what do chefs simmer?" not "what does chef simmer?"). Verb form normalization covers common auxiliaries (is/are/was/were) but not all inflections.

## Core Concepts

### Trace Vectors

Every word the model knows is represented as a sparse vector of `AbsentNumber` objects. Each slot is either *present* (the word is associated with that dimension) or *absent* (it is not). The vector has a fixed number of present slots controlled by the `sparsity` parameter.

### Operations

All reasoning uses PhantomTrace operations from the `absence-calculator` library:

| Operation | PhantomTrace | Use in Agent |
|-----------|-------------|--------------|
| `combine(a, b)` | State overlap | Building context signatures from word vectors |
| `compare(a, b)` | Directional difference | Measuring distance between vectors |
| `add(a, b)` | State accumulation | Composing semantic probes, strengthening facts |
| `erase(a, b)` | State removal with flip | Weakening facts, resolving contradictions |
| `toggle(x)` | Flip present/absent | Learning updates, vector modification |
| `n(value)` | Create a present number | Fact strength initialization |

### Trace Stores

The model maintains four separate trace stores:

- **Trace store** -- word vectors with context and topic memory banks
- **Symbol store** -- intent, action, form, and role classifications
- **Episode store** -- interaction history for episodic memory retrieval
- **Fact store** -- subject-predicate-object triples with forward and inverse lookup

Each store holds a primary vector and one or more named banks per entry, all subject to the same sparsity constraint.

### Fact Lifecycle

Facts have a strength value stored as a PhantomTrace `AbsentNumber`:

1. A new fact starts with strength `n(1)` -- a present 1.
2. Teaching the same fact again adds `n(1)` to its strength.
3. A contradicting fact (same subject + predicate, different object) erases the old fact's strength.
4. Periodic decay erases `n(1)` from old facts, letting stale knowledge fade.
5. A fact becomes inactive when its strength drops to an absent state.

This mirrors how PhantomTrace arithmetic treats presence and absence: knowledge does not disappear, it transitions from present to absent.

## Training and Ingestion

```python
model.train_on_text("gardeners water orchids gently.", epochs=1)

model.ingest_text_corpus(long_text, trace_budget_per_sentence=96)

model.ingest_file("corpus.txt")

model.ingest_url("https://example.com/article")
```

The `seed_lexicon.txt` file included in the repository provides 60 dictionary-style definitions that bootstrap the model's vocabulary and fact base. Ingesting the full lexicon at dim=512 takes several minutes.

## HTTP Service

PhantomReason includes an HTTP service:

```bash
phantomreason-serve --host 127.0.0.1 --port 8080 --dim 512 --sparsity 47
```

Or with authentication:

```bash
export PHANTOM_AGENT_API_TOKEN='your-secret-token'
phantomreason-serve --host 127.0.0.1 --port 8080
```

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/health` | No | Service and model status |
| `GET` | `/evaluate` | Yes | Run the built-in evaluation harness |
| `POST` | `/query` | Yes | Route a prompt through the reasoning pipeline |
| `POST` | `/teach` | Yes | Train on new text |
| `POST` | `/ingest` | Yes | Ingest text, file, or URL |
| `POST` | `/focus` | Yes | Set focus mode or focus text |
| `POST` | `/checkpoint` | Yes | Save model state to disk |

### Example Requests

```bash
# Query
curl -X POST http://localhost:8080/query \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "what do chefs simmer?"}'

# Teach
curl -X POST http://localhost:8080/teach \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "vector means an ordered list used for state", "epochs": 1}'

# Ingest from URL
curl -X POST http://localhost:8080/ingest \
  -H "Authorization: Bearer $PHANTOM_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'
```

## Data Storage

Runtime state is stored in the current working directory by default:

- `words` -- the learned vocabulary, one word per line
- `phantom_model_state.json` -- all vectors, banks, facts, episodes, and symbols

Set `PHANTOM_DATA_DIR` to store state in a custom location:

```bash
export PHANTOM_DATA_DIR=/var/lib/phantomreason
phantomreason-serve --host 127.0.0.1 --port 8080
```

## Evaluation

Run the built-in evaluation harness to verify the model works correctly:

```bash
phantomreason-eval
```

This tests fact recall, contradiction handling, decay behavior, and sentence parsing.

## As an LLM Augmentation Layer

PhantomReason is designed to complement large language models, not replace them. A future integration package can use the agent as:

- **A grounded fact store.** Teach the agent verified facts and query it before passing context to an LLM. The agent's symbolic confidence scores tell you which facts are reliable.
- **A contradiction detector.** When new information conflicts with stored knowledge, the agent's erasure mechanics make the conflict explicit rather than silently overwriting.
- **An interpretable memory layer.** The agent's trace vectors and fact strengths are fully inspectable -- you can trace *why* a particular answer was retrieved.
- **A retrieval filter.** Use the agent's `rank_candidates` and `retrieve_fact` to select relevant context for an LLM prompt, with transparent distance scores.

The boundary is clean: PhantomReason handles memory, confidence, and symbolic retrieval. The LLM handles natural language generation and broad world knowledge.

## Interactive Mode

For experimentation and debugging:

```bash
python -c "from phantomreason import PhantomLanguageModel, run_interactive_test; run_interactive_test(PhantomLanguageModel(dim=512, sparsity=47))"
```

The first run takes 30-40 seconds while trace vectors are computed. Subsequent runs with persisted state start in under 5 seconds.

Commands in interactive mode:

| Command | Description |
|---------|-------------|
| `teach <text>` | Train on new text |
| `ingest <file>` | Ingest a local text file |
| `scrape <url>` | Ingest from a URL |
| `focus <text>` | Prime focus mode on specific text |
| `focus on` / `focus off` | Toggle focus mode |
| `inspect <prompt>` | Show the top-ranked candidate and its trace comparison |
| Any other text | Route through the full reasoning pipeline |

## Project Structure

```
phantomreason/
  __init__.py       Package exports
  model.py          Core reasoning engine (PhantomLanguageModel)
  traces.py         PhantomTrace operation wrappers
  stores.py         Sparse trace vector storage (TraceStore)
  storage.py        Vocabulary and state path management
  corpus.py         Text normalization, sentence splitting, URL fetching
  service.py        HTTP service with auth and metrics
  evaluate.py       Built-in evaluation harness
```

## Requirements

- Python 3.11+
- [`PhantomTrace`](https://pypi.org/project/phantomtrace/) >= 0.5.0

No other dependencies. No PyTorch, TensorFlow, NumPy, or any ML framework.

## License

MIT
