Metadata-Version: 2.4
Name: qreflex
Version: 0.0.1
Summary: QreFLEX (reFLEX) — a small transformer with a gated, trainable experience-retrieval side channel: reason first, consult learned experience when useful, reason again.
Author: Qarvexium
License: Apache-2.0
Project-URL: Homepage, https://qarvexium-ops.github.io/Qs/index.html
Project-URL: Repository, https://huggingface.co/qvx-o
Keywords: transformer,language-model,retrieval-augmented-generation,experience-replay,reflex
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1
Requires-Dist: tokenizers>=0.15
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.23
Requires-Dist: pydantic>=2.0
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# reFLEX-v1-15M

**reFLEX** — *Responsive Flexible Learning and EXperience* — is a small experimental conversational language model designed around a different idea from a conventional "everything is attention" transformer.

Rather than relying entirely on the main language model to produce a response, reFLEX separates parts of the conversational process into three components:

* **Main** — the primary language-generation network.
* **Experience** — a lightweight retrieval/context component that can surface potentially useful information from previous experience.
* **Intent** — a small component intended to help interpret the nature of the input.

The result is a roughly **15M-parameter** model with an unusual parameter distribution:

| Component  | Parameters |
| ---------- | ---------: |
| Main       |       ~14M |
| Experience |      ~0.8M |
| Intent     |      ~0.2M |
| **Total**  |   **~15M** |

## What is reFLEX?

reFLEX is primarily an **experimental conversational model**, not a factual knowledge model.

It was trained on conversational-style data rather than a large factual corpus. Consequently, it should **not** be expected to reliably answer factual questions such as:

> What is the capital of France?

Its interesting behavior appears much more clearly in ordinary conversation.

For example:

```text
A: Hello
B: Hello

A: How are you?
B: Fine.

A: What's up?
B: Not much. Just hanging out.
```

The model can produce surprisingly conversational responses despite its very small parameter count.

## Architecture

reFLEX moves away from the idea that every part of the system needs to be represented by a large attention-based language model.

Its conceptual structure is:

```text
                 Input
                   │
                   ▼
              ┌─────────┐
              │ Intent  │
              └────┬────┘
                   │
                   ▼
              ┌─────────┐
              │Experience│
              └────┬────┘
                   │
                   ▼
              ┌─────────┐
              │  Main   │
              │  Model  │
              └────┬────┘
                   │
                   ▼
                Response
```

The **Experience** component can be thought of as a lightweight helper that effectively says:

> "These topics or pieces of information might be useful here."

It is not intended to replace the main language model.

## Parameter Distribution

One of the notable properties of reFLEX-v1-15M is that the total parameter count is not divided evenly between its components.

Approximately:

* **Main:** 14M parameters
* **Experience:** 0.8M parameters
* **Intent:** 0.2M parameters

This means the majority of the model's capacity remains dedicated to language generation, while relatively small components provide additional processing.

## Intended Use

reFLEX-v1-15M is intended for:

* Experimental conversational AI
* Research into modular language-model architectures
* Studying small language models
* Exploring retrieval/experience-assisted generation
* Conversational behavior experiments
* Educational experimentation with transformer architectures

## Limitations

reFLEX-v1-15M is **not** a general-purpose assistant.

It has several important limitations:

* It has very limited factual knowledge.
* It can hallucinate heavily.
* Responses may be grammatically incorrect or semantically unrelated.
* It may produce abrupt or unusual responses.
* It may repeat itself.
* It may exhibit inconsistent conversational behavior.
* Its responses can vary substantially between generations.
* It was not trained to follow instructions reliably.
* It should not be used for factual, medical, legal, financial, or safety-critical applications.

The model's unusual conversational personality should be considered an **emergent property of the training and architecture**, not an indication of human-like understanding.

## Conversational Behavior

An interesting characteristic observed during testing is that reFLEX sometimes reacts differently depending on the **social tone** of an input.

Informal testing produced behavior roughly resembling:

| Input style | Observed behavior                  |
| ----------- | ---------------------------------- |
| Positive    | Dramatic / enthusiastic            |
| Neutral     | Introverted / brief                |
| Negative    | Defensive / sarcastic              |
| Confusing   | Uncertain / existential            |
| Commands    | Occasionally resistant or confused |

These behaviors are **observations from experimentation, not guaranteed capabilities**.

For example:

```text
A: You're pretty cool.
B: No.
```

and:

```text
A: I appreciate the effort.
B: You're an idiot.
```

The model can also produce unexpectedly ordinary conversational responses:

```text
A: What's up?
B: Just got back from the park with my dog.
```

This makes reFLEX particularly interesting as a research experiment despite its extremely small size.

## Experience Ablation

Testing with and without the Experience component showed that Experience can substantially alter the generated response.

However, because the model was not trained specifically as a factual QA system, activating Experience does **not** guarantee factual correctness.

For this reason, Experience should be understood as a mechanism for influencing generation through contextual information rather than as a conventional knowledge database.

## Generation

A basic example using the `qreflex` package:

```python
from qreflex import reFLEX

model = reFLEX(
    directory=r"D:\QED\REFLEX\flex", # Or repo: qvx-o/reFLEX-v1-15M
    from_pretrained=True, # if repo dont use
    checkpoint_file=r"D:\QED\REFLEX\flex\reFLEX-v1-15M.pt", # if rpeo dont use
)

question = "What's up?"

answer = model.generate(
    f"A: {question}\nB:",
    use_experience=True,
    stop=["\nA: ", "\nB:"]
)

print(f"A: {question}\nB:", answer)
```

## Benchmarking

A conversational benchmark was created specifically for reFLEX-v1-15M.

The benchmark contains examples covering several conversational categories, including:

* Greetings
* Casual conversation
* Positive statements
* Affection
* Commands
* Negative statements
* Criticism
* Confusing inputs

The benchmark is intended primarily to demonstrate **behavioral characteristics**, rather than conventional language-model performance.

## Important Note

reFLEX-v1-15M is intentionally small.

Its purpose is not to demonstrate that a 15M model can compete with large language models on factual knowledge or general reasoning.

Instead, reFLEX explores a different question:

> **How much conversational behavior can emerge from a very small language model when some responsibilities are moved outside the main language generator?**

The model is experimental, imperfect, and occasionally bizarre — but that is part of what makes it interesting.

## Disclaimer

**reFLEX-v1-15M is an experimental conversational model.**

It may produce unexpected, sarcastic, dramatic, nonsensical, or otherwise strange responses. Do not interpret its outputs as authoritative information.
