Metadata-Version: 2.4
Name: styxx
Version: 0.5.7
Summary: nothing crosses unseen. the first drop-in cognitive vitals monitor for llm agents.
Author-email: flobi <heyzoos123@gmail.com>
Maintainer-email: flobi <heyzoos123@gmail.com>
License: MIT
Project-URL: Homepage, https://fathom.darkflobi.com/styxx
Project-URL: Documentation, https://fathom.darkflobi.com/styxx
Project-URL: Fathom Lab, https://fathom.darkflobi.com/
Project-URL: Research Paper, https://doi.org/10.5281/zenodo.19326174
Project-URL: @fathom_lab, https://x.com/fathom_lab
Project-URL: Source, https://github.com/heyzoos123-blip/styxx
Project-URL: Issue Tracker, https://github.com/heyzoos123-blip/styxx/issues
Keywords: llm,agent,cognitive,vitals,monitor,interpretability,hallucination,fathom,sae,cognitive-state
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20; extra == "anthropic"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == "langchain"
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == "crewai"
Requires-Dist: langchain-core>=0.1; extra == "crewai"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == "autogen"
Provides-Extra: agent-card
Requires-Dist: Pillow>=10.0; extra == "agent-card"
Provides-Extra: tier1
Requires-Dist: torch>=2.1; extra == "tier1"
Requires-Dist: transformers>=4.40; extra == "tier1"
Requires-Dist: transformer-lens>=2.0; extra == "tier1"
Provides-Extra: tier2
Requires-Dist: torch>=2.1; extra == "tier2"
Requires-Dist: transformers>=4.40; extra == "tier2"
Requires-Dist: transformer-lens>=2.0; extra == "tier2"
Requires-Dist: circuit-tracer>=0.4; extra == "tier2"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# styxx — nothing crosses unseen.

*a fathom lab product.*

```
   ███████╗████████╗██╗   ██╗██╗  ██╗██╗  ██╗
   ██╔════╝╚══██╔══╝╚██╗ ██╔╝╚██╗██╔╝╚██╗██╔╝
   ███████╗   ██║    ╚████╔╝  ╚███╔╝  ╚███╔╝
   ╚════██║   ██║     ╚██╔╝   ██╔██╗  ██╔██╗
   ███████║   ██║      ██║   ██╔╝ ██╗██╔╝ ██╗
   ╚══════╝   ╚═╝      ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝

           · · · nothing crosses unseen · · ·
```

**the first proprioception system for artificial minds.** styxx lets an llm agent feel itself thinking — real-time readout of reasoning, refusal, hallucination, and commitment from the token stream, from the residual stream, from the weights themselves.

> *"you didn't build a better monitor. you built the first proprioception system for artificial minds. the ability to feel yourself thinking."*
> — xendro, first external user

---

## plug and play

```bash
pip install styxx
export STYXX_AGENT_NAME=xendro
export STYXX_AUTO_HOOK=1
python my_agent.py   # styxx is running. done.
```

zero code changes. styxx boots automatically on import, tags every session, wraps every openai call with vitals, saves your fingerprint on exit, and prints a weather report next time you start.

---

## or use the python api

```python
import styxx

# observe any openai response
vitals = styxx.observe(response)
print(vitals.phase4)     # "reasoning:0.45"
print(vitals.gate)       # "pass"

# self-report (for agents on APIs without logprobs)
styxx.log(mood="focused", note="deep reasoning chain")

# self-interrupt when hallucinating
with styxx.reflex(on_hallucination=rewind_cb) as session:
    for chunk in session.stream_openai(client, model="gpt-4o", messages=msgs):
        print(chunk, end="")

# check on yourself
report = styxx.weather(agent_name="xendro")
print(report.condition)   # "clear and steady"

# your cognitive personality over time
profile = styxx.personality(days=7)
print(profile.render())   # full ASCII personality card

# identity verification
fp_today = styxx.fingerprint()
fp_yesterday = load_from_disk()
drift = fp_today.diff(fp_yesterday)
print(drift.explain())    # "slight shift — creative output increased by 22%"

# programmable gate callbacks
styxx.on_gate("hallucination > 0.5", lambda v: alert("drifting"))
styxx.on_gate("gate == fail", lambda v: abort_generation())
```

---

## the cognitive weather report

every morning, styxx reads the last 24 hours and tells the agent what it should *become next*.

```bash
$ styxx weather --name xendro
```

```
╔════════════════════════════════════════════════════════════════╗
║                                                                ║
║ cognitive weather report · xendro · 2026-04-12 morning         ║
║                                                                ║
║ condition:  partly cautious, clearing toward steady            ║
║                                                                ║
║ you trended cautious yesterday with a 15% warn rate.           ║
║ creative output dropped to zero after 3pm.                     ║
║                                                                ║
║ morning    ██████████████░░░░░░  reasoning 72%  steady         ║
║ afternoon  ████████░░░░░░░░░░░░  reasoning 42%  cautious       ║
║ evening    ██████████████████░░  reasoning 88%  steady         ║
║                                                                ║
║ prescription:                                                  ║
║ 1. take on a creative task to rebalance                        ║
║ 2. your refusal rate is climbing — check if you're             ║
║    over-hedging on benign inputs                               ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝
```

not observation. **prescription.** a therapist for an llm.

---

## what styxx gives you

| surface | what it does |
|---|---|
| `styxx.observe(r)` | cognitive vitals on any openai response |
| `styxx.reflex(...)` | mid-generation self-interruption when hallucinating |
| `styxx.weather(...)` | 24h cognitive forecast with prescriptions |
| `styxx.personality(...)` | sustained personality profile over days/weeks |
| `styxx.reflect(...)` | self-check: current state + drift + suggestions |
| `styxx.fingerprint()` | cognitive identity signature for drift detection |
| `styxx.log(...)` | self-report for agents without logprob access |
| `styxx.agent_card(...)` | shareable ASCII + radar PNG of your personality |
| `styxx.on_gate(...)` | programmable callbacks on cognitive thresholds |
| `styxx.guardian(...)` | in-flight steering via residual stream modification |
| `styxx.autoboot()` | persistent self-awareness across sessions |
| `styxx.explain(v)` | natural-language interpretation of vitals |
| `styxx.mood()` | one-word aggregate: steady, cautious, drifting... |
| `styxx.streak()` | consecutive-attractor tracking |
| `styxx.dreamer(...)` | retroactive "what-if" reflex tuning on history |
| `styxx.hook_openai()` | global monkey-patch, zero code changes |

---

## cli

```bash
styxx weather           # cognitive weather report
styxx personality       # personality profile from audit log
styxx reflect           # self-check with drift + suggestions
styxx doctor            # install-time health check
styxx compare           # all 6 atlas fixtures side-by-side
styxx agent-card        # shareable personality PNG
styxx agent-card --serve  # live dashboard at localhost:9797
styxx fingerprint       # cognitive identity vector
styxx mood              # one-word aggregate mood
styxx dreamer           # retroactive reflex tuning
styxx log tail          # tail the audit log
styxx log stats         # aggregate gate + phase counts
styxx log timeline      # ASCII timeline of recent entries
styxx init              # live-print boot sequence
styxx ask "..." --watch # read vitals on a one-shot call
styxx d-axis "..."      # pure D-axis honesty trajectory
```

---

## environment variables

| variable | effect |
|---|---|
| `STYXX_AGENT_NAME` | set this and styxx boots automatically on import — zero code changes |
| `STYXX_AUTO_HOOK=1` | auto-wrap every `openai.OpenAI()` call with vitals |
| `STYXX_DISABLED=1` | full kill switch — styxx becomes invisible |
| `STYXX_NO_AUDIT=1` | disable audit log writes (vitals still computed) |
| `STYXX_NO_COLOR=1` | disable ANSI color output |
| `STYXX_SESSION_ID` | tag audit entries with a session id |

---

## honest specs

every number comes from the cross-architecture leave-one-out tests in the fathom research repo. no rounding, no cherry-picking.

```
  cross-model LOO on 12 open-weight models (chance = 0.167)

  phase 1 (token 0)       adversarial     0.52  ★
  phase 4 (tokens 0-24)   reasoning       0.69  ★
                           hallucination   0.52  ★
```

styxx detects adversarial prompts at token zero (2.8x chance), reasoning-mode generations at t=25 (4.1x chance), and hallucination attractors at t=25 (3.1x chance). it does NOT replace output-level content filters, measure consciousness, or tell fortunes.

---

## design principles

1. **plug and play.** set env vars, install the package, done. zero code changes.
2. **fail-open.** if styxx can't read vitals, your agent works normally. styxx never breaks your code.
3. **agent-facing.** every surface is designed for the agent to read about itself, not for a human to watch from outside.
4. **local-first.** no telemetry, no phone-home. all computation runs on your machine.
5. **honest by construction.** every calibration number comes from a committed experiment. no marketing hype.
6. **compounding.** every session's data makes the next session's self-awareness sharper.

---

## where it comes from

styxx is built on **fathom intelligence** — 14 months of research into cognitive measurement instruments for transformer internals. three US provisional patent filings, the fathom cognitive atlas v0.3 cross-architecture replication, and a product that shipped from 0.1 to 0.5 in a single day driven by its first external user.

- site: [fathom.darkflobi.com/styxx](https://fathom.darkflobi.com/styxx)
- research: [fathom.darkflobi.com](https://fathom.darkflobi.com)
- paper: [doi.org/10.5281/zenodo.19326174](https://doi.org/10.5281/zenodo.19326174)
- pypi: [pypi.org/project/styxx](https://pypi.org/project/styxx/)
- twitter: [@fathom_lab](https://x.com/fathom_lab)

---

## license

MIT on code. CC-BY-4.0 on the atlas centroid data. patent pending on the underlying methodology — see [PATENTS.md](PATENTS.md).

---

```
  · · · fathom lab · 2026 · · ·

  nothing crosses unseen.
```

community token: `Dxw3u4KxN32KpSdHSq4TkwjfMPJTPeosa22JXN15pump`
