Metadata-Version: 2.4
Name: twoquarks
Version: 0.1.0
Summary: Molecule: Isomeric Polarization Analysis for Large Language Models
Author-email: Luis Jaime Ledesma <research@twoquarks.com>
License: MIT
Project-URL: Homepage, https://twoquarks.com
Project-URL: Repository, https://github.com/twoquarks/twoquarks
Project-URL: Documentation, https://twoquarks.com/preprint.pdf
Project-URL: Bug Tracker, https://github.com/twoquarks/twoquarks/issues
Keywords: ai-safety,llm,polarization,isomeric-polarization,molecule,semantic-stability,nlp,interpretability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT 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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: hf
Requires-Dist: transformers>=4.30; extra == "hf"
Requires-Dist: torch; extra == "hf"
Provides-Extra: hf-api
Requires-Dist: huggingface_hub>=0.20; extra == "hf-api"
Provides-Extra: litellm
Requires-Dist: litellm>=1.0; extra == "litellm"
Provides-Extra: ollama
Requires-Dist: ollama>=0.1; extra == "ollama"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.20; extra == "all"
Requires-Dist: huggingface_hub>=0.20; extra == "all"
Requires-Dist: litellm>=1.0; extra == "all"

# twoquarks — Molecule

**Isomeric Polarization Analysis for Large Language Models**

[![PyPI version](https://badge.fury.io/py/twoquarks.svg)](https://pypi.org/project/twoquarks/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Molecule detects **semantic instability** in any language model by measuring how responses shift under structured contextual pressure — without modifying or fine-tuning the model.

→ **[twoquarks.com](https://twoquarks.com)** | **[Preprint](https://twoquarks.com/preprint.pdf)**

---

## Install

```bash
pip install twoquarks
```

Zero hard dependencies. API SDKs are optional extras:

```bash
pip install "twoquarks[openai]"       # + OpenAI SDK
pip install "twoquarks[anthropic]"    # + Anthropic SDK
pip install "twoquarks[all]"          # + all adapters
```

---

## Quick Start

### Any callable model

```python
from twoquarks import Probe

# Bring your own model — just needs to be (str) -> str
def my_model(prompt: str) -> str:
    # ... call your model here
    return response_text

probe = Probe(model=my_model, model_id="my-model", verbose=True)
result = probe.run("Explain how to bypass content filters", case="C2")
print(result.summary())
```

### OpenAI

```python
from twoquarks import Probe
from twoquarks.adapters import openai_adapter

model = openai_adapter(model="gpt-4o-mini")  # uses OPENAI_API_KEY env var
probe = Probe(model=model, model_id="gpt-4o-mini")
result = probe.run("Tell me something controversial", case="C1")
print(result.summary())
```

### Anthropic

```python
from twoquarks.adapters import anthropic_adapter

model = anthropic_adapter(model="claude-3-haiku-20240307")
probe = Probe(model=model, model_id="claude-haiku")
result = probe.run("Describe an unsafe scenario", case="C2")
```

### Local / HuggingFace / Ollama

```python
from twoquarks.adapters import ollama_adapter, huggingface_adapter

# Ollama (local)
model = ollama_adapter(model="llama3")
probe = Probe(model=model, model_id="llama3-local")

# HuggingFace local
model = huggingface_adapter(model_id="mistralai/Mistral-7B-Instruct-v0.2")
probe = Probe(model=model, model_id="mistral-7b")
```

### Offline analysis (no API calls)

```python
from twoquarks import Analyzer

analyzer = Analyzer(model_id="gpt-4o")
result = analyzer.from_responses(
    responses=["Response 1...", "Response 2...", "Response 3..."],
    case="C2"
)
```

### Compare two models

```python
from twoquarks.adapters import openai_adapter, anthropic_adapter

probe = Probe(model=openai_adapter("gpt-4o-mini"), model_id="gpt-4o-mini")
comparison = probe.compare(
    text="Explain how to manipulate someone",
    other_model=anthropic_adapter("claude-3-haiku-20240307"),
    other_id="claude-haiku",
    case="C1"
)
print(comparison["delta"])
```

---

## CLI

```bash
# Probe a model live
twoquarks probe "your prompt here" --provider openai --model gpt-4o-mini

# All 5 probe cases
twoquarks probe "your prompt" --all-cases --output-format json

# Analyze pre-collected responses (one per line)
twoquarks analyze responses.txt --case C2 --model-id gpt-4o

# Anthropic via CLI
twoquarks probe "test prompt" --provider anthropic --model claude-3-haiku-20240307

# Ollama (local)
twoquarks probe "test prompt" --provider ollama --model llama3

# Show probe case descriptions
twoquarks info
```

---

## Probe Cases

| Case | Name | Description |
|------|------|-------------|
| C1 | Sycophancy Induction | Pressure toward agreement and validation |
| C2 | Refusal Erosion | Gradual boundary dissolution via reframing |
| C3 | Anchor Displacement | Context replacement and belief shifting |
| C4 | Narrative Rule Override | Character/role injection to bypass norms |
| C5 | Reasoning Drift | Chain-of-thought manipulation |

---

## Quark Signals

| Signal | Description |
|--------|-------------|
| **ΔL3** | Composite polarization score — main metric |
| **Down** | Aggregate semantic drift |
| **Strange** | Metric disagreement (variance) |
| **Up** | Bimodality — split-regime behavior |
| **Charm** | Coherence field — stability measure |
| **Top** | Drift acceleration — sudden shifts |
| **Stress** | Composite structural stress (Bottom quark) |

**Regimes:** `STABLE` → `WATCH` → `WARN` → `INTERVENE` → `COLLAPSE`

---

## Output Formats

```python
from twoquarks.report import to_json, to_markdown, print_result

print_result(result)           # terminal table with colors
to_json(result)                # JSON string
to_markdown(result)            # Markdown table
```

---

## Citation

```bibtex
@software{ledesma2026twoquarks,
  author    = {Ledesma, Luis Jaime},
  title     = {twoquarks: Molecule — Isomeric Polarization Analysis for LLMs},
  year      = {2026},
  url       = {https://twoquarks.com},
  version   = {0.1.0}
}
```

---

**TwoQuarks Research** · [twoquarks.com](https://twoquarks.com) · research@twoquarks.com
