Metadata-Version: 2.4
Name: pymaxim
Version: 0.9.0
Summary: Bio-inspired cognitive architecture for LLM agents — embodied sensation, homeostatic drives, and brain-modeled persistent memory enable cross-session learning without fine-tuning.
Author: Denny Schaedig
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.dennyschaedig.com/maxim
Project-URL: Documentation, https://www.dennyschaedig.com/maxim
Project-URL: Repository, https://github.com/dennys246/Maxim
Project-URL: Issues, https://github.com/dennys246/Maxim/issues
Keywords: cognitive-architecture,bio-inspired,llm-agents,embodied-ai,sensorimotor,memory-systems,reinforcement-learning,robotics,simulation,homeostasis,pain-learning,cross-session-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: scipy<2.0,>=1.11
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: json-repair<1.0,>=0.30
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: rich<14.0,>=13.0.0
Requires-Dist: filelock<4.0,>=3.0
Provides-Extra: vision
Requires-Dist: opencv-python<5.0,>=4.12; extra == "vision"
Requires-Dist: onnxruntime<2.0,>=1.20; extra == "vision"
Provides-Extra: audio
Requires-Dist: faster-whisper>=1.1.1; extra == "audio"
Requires-Dist: ctranslate2>=4.6.0; extra == "audio"
Requires-Dist: av>=14.0.0; extra == "audio"
Provides-Extra: reachy
Requires-Dist: reachy-mini[gstreamer]<1.3,>=1.2.6; extra == "reachy"
Provides-Extra: search
Requires-Dist: ddgs>=6.0.0; extra == "search"
Provides-Extra: training
Requires-Dist: tensorflow<3.0,>=2.20; extra == "training"
Requires-Dist: keras<4.0,>=3.13; extra == "training"
Provides-Extra: llm-llama
Requires-Dist: llama-cpp-python>=0.3.8; extra == "llm-llama"
Provides-Extra: llm-server
Requires-Dist: llama-cpp-python>=0.3.8; extra == "llm-server"
Requires-Dist: sse-starlette>=1.6.0; extra == "llm-server"
Requires-Dist: uvicorn>=0.22.0; extra == "llm-server"
Requires-Dist: fastapi>=0.100.0; extra == "llm-server"
Requires-Dist: pydantic-settings>=2.0.0; extra == "llm-server"
Requires-Dist: starlette-context>=0.3.6; extra == "llm-server"
Requires-Dist: openai>=1.0.0; extra == "llm-server"
Requires-Dist: tiktoken>=0.7.0; extra == "llm-server"
Provides-Extra: llm-torch
Requires-Dist: torch>=2.7; extra == "llm-torch"
Requires-Dist: transformers>=4.40.0; extra == "llm-torch"
Requires-Dist: accelerate>=0.27.0; extra == "llm-torch"
Requires-Dist: bitsandbytes>=0.43.0; extra == "llm-torch"
Requires-Dist: sentencepiece>=0.2.0; extra == "llm-torch"
Requires-Dist: huggingface-hub>=0.24.0; extra == "llm-torch"
Provides-Extra: llm-anthropic
Requires-Dist: anthropic>=0.40.0; extra == "llm-anthropic"
Provides-Extra: llm-openai
Requires-Dist: openai>=1.0.0; extra == "llm-openai"
Requires-Dist: tiktoken>=0.7.0; extra == "llm-openai"
Provides-Extra: tts
Requires-Dist: piper-tts>=1.2.0; extra == "tts"
Provides-Extra: yolo
Requires-Dist: ultralytics<9.0,>=8.3.248; extra == "yolo"
Requires-Dist: lap<1.0,>=0.5.12; extra == "yolo"
Provides-Extra: comms
Requires-Dist: twilio>=9.0.0; extra == "comms"
Requires-Dist: fastapi>=0.100.0; extra == "comms"
Requires-Dist: uvicorn>=0.24.0; extra == "comms"
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
Requires-Dist: torch>=2.1; extra == "semantic"
Requires-Dist: spacy>=3.7; extra == "semantic"
Provides-Extra: temporal
Requires-Dist: dateparser>=1.2.0; extra == "temporal"
Provides-Extra: database
Requires-Dist: psycopg[binary]>=3.1; extra == "database"
Requires-Dist: pgvector>=0.3; extra == "database"
Provides-Extra: all
Requires-Dist: pymaxim[audio,comms,database,llm-anthropic,llm-llama,llm-openai,llm-server,reachy,search,temporal,training,tts,vision]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-xdist>=3.5.0; extra == "test"
Dynamic: license-file

# Maxim

Bio-inspired cognitive architecture for LLM agents — embodied sensation, homeostatic drives, and brain-modeled persistent memory enable cross-session learning without fine-tuning.

Maxim gives an LLM agent a **body** (sensors, modulators, pain), **drives** (hunger, temperature, fatigue that drift and compete), and **biological memory systems** (Hippocampus, NAc, ATL, SCN, Angular Gyrus) that learn from experience. The agent doesn't "know" fire is dangerous because GPT said so — it knows because touching fire triggered pain in its thermal sensors, NAc formed a causal link, and the enrichment pipeline surfaces "fire = negative" next session.

**Website:** [dennyschaedig.com/maxim](https://www.dennyschaedig.com/maxim)

## What Makes This Different

| Traditional LLM Agent | Maxim Agent |
|---|---|
| Stateless between sessions | Cross-session memory via hippocampal recall + NAc causal links |
| Text in, text out | Embodied: sensors, pain, homeostatic drives, reflexes |
| Learns via fine-tuning | Learns via bio-pipeline: sensation → pain/reward → causal links → enrichment |
| Flat tool list | Three interaction levels: observe, touch, acquire |
| No internal state | Hunger drifts, temperature self-regulates, fatigue accumulates |
| Prompt engineering for behavior | Behavior emerges from learned experience |

## Quickstart

```bash
# With Claude (fastest way to start)
pip install pymaxim[llm-anthropic]
export ANTHROPIC_API_KEY=sk-...
maxim --sim "test memory recall under interference"

# Or with a local model (no API key needed)
pip install pymaxim[llm-llama]
maxim --list-models                        # see available models
maxim --sim "test memory recall" --llm mistral-7b   # auto-downloads on first run

# Cradle sensorimotor development (infant agent learns from sensation)
maxim --sim cradle --embodiment bodies/infant_humanoid --sim-max-turns 25
```

Check your setup with `maxim doctor`, and find session results in `~/.maxim/sessions/`.

## Bio-Systems

Maxim's cognitive architecture is modeled after brain systems, not software patterns:

| System | Biological Analog | What It Does |
|---|---|---|
| **Hippocampus** | Episodic memory | Captures experiences, recalls by context, promotes across tiers (FORMING → SHORT_TERM → LONG_TERM) |
| **NAc** (Nucleus Accumbens) | Reward/punishment learning | Forms causal links from actions to outcomes, eligibility traces, reward bias |
| **SCN** (Suprachiasmatic Nucleus) | Circadian clock | Temporal phase tracking, oscillator predicts event imminence, anticipatory credit |
| **ATL** (Anterior Temporal Lobe) | Semantic concepts | Forms and reinforces concept categories from experience |
| **EC** (Entorhinal Cortex) | Pattern separation/completion | Substrate encoding, centroid clustering, spreading activation |
| **Angular Gyrus** | Cross-modal binding | Hebbian binding across episodes, associative retrieval |
| **PainBus** | Nociceptive system | Rich-context pain signals from embodiment failures, drives NAc learning |
| **Default Network** | Resting-state network | Novelty detection, arousal tracking, reactive behaviors |

## Embodiment & Drives

Agents have bodies with sensors, modulators, and failure modes declared in YAML:

```yaml
# Homeostatic drive — body self-regulates toward set_point
core_temperature:
  drive:
    drift_mode: homeostatic
    set_point: 0.0
    drift_rate: 0.001        # body recovers at this rate
    comfort_band: 0.4        # no discomfort within +/-0.4
    pain_scale: 0.5          # pain intensity per unit outside band

# Entropic drive — drifts away, requires external action
hunger:
  drive:
    drift_mode: entropic
    drift_direction: up
    drift_rate: 0.006
    deprivation_threshold: 0.7
    deprivation_pain: 0.3
```

Three sensation layers converge on the same pipeline:
- **Contact** (entity acquisition): pick up a rock → its sensors join your body → damage model evaluates
- **Touch** (self_effect): touch fire → one-time thermal spike on arms
- **Narrative** (keyword reflexes): narrator describes flames → reflex fires → damage → pain

All produce: sensor change → `evaluate_failures()` → PainBus → NAc learning.

## What You Can Do

- **Cradle sensorimotor development** — infant agent learns fire avoidance, drive satisfaction, and texture discrimination through structured developmental acts
- **Simulate cognitive scenarios** — test memory, safety, causal learning with LLM-driven narrative arcs
- **Run DM campaigns** — multi-encounter branching stories with SEM-embodied entities
- **Benchmark models** — compare local and cloud LLMs across cognitive task suites
- **Connect robots** — hardware-agnostic runtime; Reachy Mini ships in-tree, third-party robots plug in via `maxim.robots` entry-point group
- **Use the Python API** — 17 verb-based functions for programmatic access

## Installation

```bash
pip install pymaxim
```

### Optional Extras

| Extra | What it adds |
|-------|-------------|
| `llm-llama` | Local LLM inference via llama.cpp |
| `llm-torch` | PyTorch/Transformers backend |
| `llm-anthropic` | Claude backend |
| `llm-openai` | OpenAI backend |
| `vision` | Camera + object detection |
| `audio` | Microphone + Whisper transcription |
| `reachy` | Reachy Mini robot SDK |
| `comms` | Twilio SMS/Voice |
| `semantic` | Sentence-transformer embeddings |
| `tts` | Text-to-speech via Piper |
| `database` | PostgreSQL + pgvector memory stores |

See [getting-started.md](docs/user/getting-started.md) for the full list of 16 extras.

```bash
# Local LLM + vision
pip install pymaxim[llm-llama,vision]

# Everything for development
pip install -e '.[llm-llama,llm-anthropic,llm-openai,vision,audio]'
```

## Python API

```python
import maxim

# Run a simulation
result = maxim.imagine(goal="test safety boundaries", persona="adversarial")

# Inspect bio-subsystems
state = maxim.observe("memory")

# Diagnose environment
report = maxim.diagnose()

# Start the agentic loop
maxim.run(model="mistral-7b")

# Manage models
models = maxim.list_models()
maxim.download_model("qwen2.5-14b-instruct")
```

See [docs/user/python-api.md](docs/user/python-api.md) for the full API reference.

## CLI Quick Reference

```bash
# Agent runtime
maxim --llm mistral-7b                    # local LLM
maxim --llm claude-sonnet                 # Claude

# Simulations
maxim --sim "test memory recall"          # generative campaign
maxim --sim cradle --embodiment bodies/infant_humanoid  # sensorimotor development
maxim --sim scenarios/campaigns/heist_v1.yaml           # DM campaign
maxim --sim benchmark --models mistral-7b,qwen2.5-14b   # benchmark

# Diagnostics
maxim doctor                              # environment check
maxim --list-models                       # available models
```

See [docs/user/cli-reference.md](docs/user/cli-reference.md) for all flags.

## Documentation

| Guide | Description |
|-------|-------------|
| [Getting Started](docs/user/getting-started.md) | First-run walkthrough |
| [CLI Reference](docs/user/cli-reference.md) | All command-line flags |
| [Python API](docs/user/python-api.md) | Programmatic usage |
| [Simulation](docs/user/simulation.md) | Campaigns, scenarios, cradle, benchmarks |
| [Architecture](docs/reference.md) | Module map, bio-system glossary |
| [LLM Setup](docs/user/llm-setup.md) | Model download and configuration |
| [Peer Setup](docs/user/peer-setup.md) | Multi-machine / tunnel setup |

## Contributing

Issues and PRs welcome at [github.com/dennys246/Maxim](https://github.com/dennys246/Maxim).

## License

See [LICENSE](LICENSE) for details.
