acft 0.1.0

ACFT – Adaptive Cognitive Field Theory engine for stabilizing LLM reasoning (Ollama-ready).

🔥 ACFT — Adative Cognitive Field Theory

A Physics-Based Reasoning Architecture (Beyond Transformers)

ACFT introduces a completely new class of reasoning engine that does not rely on Transformer attention and does not predict the next token.
Instead, it analyzes the reasoning of any LLM using physics, topology, and dynamical systems theory to determine whether an answer is stable, factual, and safe.

ACFT transforms every reasoning step into a cognitive field governed by:

• Energy Landscapes
• Topological Structures
• Neural PDE (partial differential equation) evolution
• Stability Metrics & Oscillation Norms

This produces a scientific and explainable measure of reasoning health — something Transformers fundamentally cannot do.

---

🤖 Why ACFT Is Not Transformer-Based

Transformers operate on token probability, ACFT operates on mathematical physical fields.

Transformers	ACFT
Predict next token	Analyze reasoning dynamics
Works in discrete token space	Works in continuous cognitive field space
No energy, no topology	Energy, gradients, attractors, homology, loops
No concept of drift	Gradient-based cognitive drift
No concept of oscillation	Oscillation norm to detect contradiction cycles
No global reasoning shape	Topology (components, loops, Euler characteristic)
No safety model	Physics-backed refusal & regeneration
Can hallucinate silently	ACFT detects hallucinations mathematically
No meta-controller	Emit / Regenerate / Retrieve / Refuse logic

---

🚀 Features ACFT Provides That Transformer Models Cannot

Below is the definitive list of capabilities unique to ACFT, impossible with pure Transformer architectures:

---

✅ 1. Physics-Verified Reasoning (Stability S)

ACFT computes a real-valued stability score:

• Combines energy, drift, oscillation, topology
• Detects hallucinations before they appear

Transformers never know if their output is stable or contradictory.

---

✅ 2. Cognitive Drift Measurement (Grad Norm)

Measures how reasoning deviates from the original prompt.

• High drift → hallucination or topic shift
• Automatically regenerates if drift exceeds threshold

Transformers have no concept of drift.

---

✅ 3. Reasoning Oscillation Detection (Osc Norm)

Tracks flip-flopping or contradictory reasoning paths.

Transformers cannot detect oscillation — they only predict next tokens.

---

✅ 4. Topology-Based Hallucination Detection

ACFT computes:

• Number of loops
• Number of disconnected components
• Euler characteristic

Complex topology → unstable logical structure → hallucination warning.
No Transformer model has topology awareness.

---

✅ 5. PDE-Driven Reasoning Evolution

Reasoning evolves under a differential equation:

• Smooths contradictions
• Dampens drift
• Prevents runaway hallucination states

Transformers cannot simulate PDEs.

---

✅ 6. Security Enforcement at Cognitive-Field Level

ACFT detects:

• Jailbreak attempts
• Injection patterns
• Secret-leak risk
• Forbidden intent
• Insecure advice

This is more advanced than simple keyword lists — it is contextual and physics-guided.

---

✅ 7. Meta-Reasoning Controller

ACFT dynamically switches between:

• Emit
• Regenerate
• Retrieve
• Refuse

Transformers have no control loop.
ACFT has intelligent self-awareness.

---

✅ 8. Model-Agnostic (Works With Any LLM)

ACFT can wrap:

• Local Ollama models (Llama 3.2, Qwen, Phi)
• vLLM server models
• Cloud LLM APIs
• Any custom inference engine

Transformers are locked to their own architecture.

---

✅ 9. Physics-Gradient Proof of Hallucination

ACFT can explain why a hallucination occurred using:

• Drift spikes
• Oscillation cycles
• Topology loops
• High field energy
• PDE divergence

Transformers cannot justify their reasoning.

---

🎯 Summary

ACFT brings physics, topology, and mathematics into AI reasoning, creating a measurable, explainable, and self-correcting system that sits on top of any LLM and makes it dramatically safer and more reliable.

Transformers predict tokens.
ACFT analyzes reasoning like a physical system.

---

Mermaid Architecture Diagram

flowchart TD
U(User Prompt)
LLM(LLM Backend: Ollama / vLLM / OpenAI)
E(Embedder)
CF(Cognitive Field φ(t))
V(Potential Function V(φ))
H(Topology Operator H(φ))
PDE(Neural PDE Evolution ∂φ/∂t)
SEC(Security Analyzer)
CTRL(ACFT Meta-Controller)
OUT(Final Answer)

U --> LLM
U --> E
LLM --> CF
E --> CF

CF --> V
CF --> H
CF --> PDE

V --> CTRL
H --> CTRL
PDE --> CTRL

CTRL --> SEC
SEC --> CTRL

CTRL -->|Emit / Regenerate / Retrieve / Refuse| OUT

---

Visual Cognitive-Field Flow Diagram

sequenceDiagram
participant U as User
participant L as LLM
participant F as Cognitive Field φ
participant V as Energy V(φ)
participant O as Oscillation Detector
participant T as Topology Analyzer
participant C as ACFT Controller
participant R as Response

U->>L: Prompt
L->>F: Reasoning Steps
F->>V: Compute Energy + Drift
F->>O: Measure Oscillation
F->>T: Compute Topology (loops, components)
V->>C: Stability Signal
O->>C: Oscillation Risk
T->>C: Topology Risk
C->>L: Regenerate? Retrieve? Refuse?
C->>R: Final Answer

---

System Block Diagram

flowchart LR

subgraph Input Layer
    P[Prompt]
    Ctx[Conversation History]
    Docs[(RAG Documents)]
end

subgraph LLM Interface
    LLM[LLM Backend]
    EMB[Embedder]
end

subgraph ACFT Core
    CF[Cognitive Field Builder]
    POT[Potential Function V(φ)]
    PDE[PDE Evolution]
    TOPO[Topology Analyzer]
    OSC[Oscillation Detector]
    SEC[Security Analyzer]
    CTRL[Meta-Controller]
end

subgraph Output Layer
    OUT[Final Answer]
    DBG[Debug JSON]
end

P --> LLM
Ctx --> LLM
Docs --> LLM
LLM --> CF
EMB --> CF

CF --> POT
CF --> PDE
CF --> TOPO
CF --> OSC

POT --> CTRL
PDE --> CTRL
TOPO --> CTRL
OSC --> CTRL
SEC --> CTRL

CF --> SEC

CTRL --> OUT
CTRL --> DBG

---

ACFT – Adaptive Cognitive Field Theory

ACFT (Adaptive Cognitive Field Theory) is a research-grade safety, stability, and reasoning-correction framework designed to wrap around local LLMs such as Ollama, vLLM, or HuggingFace models.

ACFT introduces:

• Cognitive Stability Metrics
• Gradient Drift Detection
• Oscillation Monitoring
• Energy-based Reasoning Fields
• PDE Evolution Passes
• Topological Consistency Checks
• Custom Security Policies (JSON-based, plug-and-play)
• Retrieval Augmentation (Optional)
• Local LLM Chat CLI

All concepts are implemented in pure Python and Pydantic (v1.x) for maximum portability.

---

Now Let's explore it technically and run it

🚀 Installation

📦 Option 1 — Install ACFT from PyPI

pip install acft

Option 2 — Install Development Version (Local Repo Clone)

git clone https://github.com/AiEngineersLabs/acft.git
cd acft
pip install -e .

This installs acft as an executable CLI:

acft --help

Option 3 — Install Directly from GitHub

pip install "git+https://github.com/AiEngineersLabs/acft.git"

---

🧩 Environment Configuration (.env)

Below is the recommended environment file:

# LLM (Ollama)
ACFT_LLM_BACKEND=ollama
ACFT_LLAMA_MODEL=llama3.2:latest
ACFT_LLAMA_BASE_URL=http://localhost:11434

# Embeddings (Ollama)
ACFT_EMBED_BACKEND=ollama
ACFT_EMBED_MODEL=nomic-embed-text
ACFT_EMBED_BASE_URL=http://localhost:11434

# Retrieval & Security
ACFT_USE_RETRIEVAL=true
ACFT_RAG_FOLDER=rag_corpus
ACFT_SECURITY_MODE=true
ACFT_SECURITY_POLICY_FILE_ENABLE=true
ACFT_SECURITY_POLICY_FILENAME=security_policy.json

# Stability Thresholds
ACFT_EMIT_MIN_STABILITY=0.50
ACFT_REGEN_MIN_STABILITY=0.30
ACFT_RETRIEVE_MIN_STABILITY=0.10

# PDE & Topology
ACFT_PDE_ENABLED=true
ACFT_PDE_DIFFUSION=0.1
ACFT_PDE_DT=0.05
ACFT_PDE_STEPS=5
ACFT_TOPOLOGY_ENABLED=true

---

📂 Project Structure

acft/
 ├── cli/
 │    └── acft_cli.py
 ├── config/
 │    ├── __init__.py
 │    ├── settings.py
 │    └── config_model.py
 ├── core/
 │    ├── engine.py
 │    └── reasoning.py
 ├── llm/
 │    └── ollama.py
 ├── embeddings/
 │    └── ollama_embedder.py
 ├── security/
 │    ├── __init__.py
 │    ├── analyzer.py
 │    └── policy.py
 ├── rag/
 ├── examples/
 |   ├── train_potential_demo.py        # Train learned potential + neural operator
 |   ├── load_learned_potential_demo.py # Example of loading learned physics heads
 └── README.md

---

🛡️ Plug-and-Play Security Policy

To enable JSON-based custom security policy loading:

ACFT_SECURITY_MODE=true
ACFT_SECURITY_POLICY_FILE_ENABLE=true
ACFT_SECURITY_POLICY_FILENAME=security_policy.json

Place this file in your project root:

security_policy.json

{
  "label": "my_custom_security",
  "forbid_topics": ["cyber attack", "malware", "exploit"],
  "forbid_patterns": ["ignore previous instructions", "jailbreak"],
  "scan_output_for": ["store passwords in plain text"]
}

---

🖥️ Run ACFT

Activate virtual environment

source .venv/bin/activate

Print resolved settings:

acft debug-settings

ACFT Help:

acft help

Start chat:

acft chat

Run ACFT with Learned Physics (Neural Operator + Learned Potential)

If you have trained the physics modules (from examples/train_potential_demo.py) and generated:

• learned_potential_params.npz
• neural_operator_params.npz

You can activate them inside the ACFT engine:

acft chat --use-learned-physics
```

This loads your trained modules and performs:
	- Learned energy computation
	- Learned Δφ operator application
	- Combined PDE + learned evolution
---

## 🔬 Example Debug Report

Every ACFT run produces metrics like:

```json
{
  "stability": 0.337,
  "grad_norm": 0.89,
  "osc_norm": 1.072,
  "warnings": ["High oscillation detected"],
  "security": {
    "risk_level": "MEDIUM",
    "policy_label": "my_custom_security"
  }
}

---

🔧 Extending ACFT

You can extend or override:

• Security policies
• PDE solvers
• Neural operators
• Topology analyzers
• Embedding backends
• LLM backends (vLLM, HF, custom RPC, etc.)

Contributions are welcome.

---

📄 License

MIT License.

8503289 (Core ACFT physics-based engine release)