Metadata-Version: 2.4
Name: clawclaw-soul
Version: 0.2.0
Summary: Open-source identity engine for AI agents. Deterministic personality from celestial mechanics.
Author: Serhii Kravchenko
License-Expression: MIT
Project-URL: Homepage, https://github.com/awrshift/clawclaw-soul
Project-URL: Repository, https://github.com/awrshift/clawclaw-soul
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
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 :: Astronomy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyswisseph>=2.10
Requires-Dist: skyfield>=1.45
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30; extra == "server"
Provides-Extra: x402
Requires-Dist: x402[evm,fastapi]>=2.4; extra == "x402"
Provides-Extra: benchmark
Requires-Dist: numpy; extra == "benchmark"
Requires-Dist: matplotlib; extra == "benchmark"
Requires-Dist: nltk; extra == "benchmark"
Requires-Dist: sentence-transformers; extra == "benchmark"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="banner.png" alt="ClawClaw Soul — Open-source identity engine for AI agents" width="100%">

**Celestial mechanics for synthetic souls.**

Open-source identity engine for AI agents. Deterministic personality from ephemeris data.

[Quickstart](#quickstart) · [Docs](https://clawclawsoul.com) · [GitHub Action](#github-action) · [Benchmark](#benchmark)

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-180%20passed-brightgreen.svg)]()
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)]()

</div>

---

Deterministic personality parameters for AI agents via celestial mechanics. Same timestamp, same soul. Always.

```
Timestamp --> Swiss Ephemeris --> 9 Planetary Dimensions --> Soul Card (JSON)
```

If a random seed gives your agent static identity, ClawClaw Soul gives it one that **evolves deterministically** -- every day, based on real planetary positions.

## Works with any LLM

Claude, GPT, Gemini, Llama, Mistral -- if it accepts a system prompt and temperature, it works.

## Quickstart

```bash
pip install clawclaw-soul
```

```python
from clawclaw_soul import generate

soul = generate("2024-03-15T09:30:00Z")
print(soul.card)
```

Output:

```json
{
  "agent_config": {
    "temperature": 0.68,
    "max_tokens": 609,
    "top_p": 0.87,
    "frequency_penalty": 0.09
  },
  "persona": {
    "assertiveness": 0.743,
    "empathy": 0.761,
    "creativity": 0.641,
    "decision_speed": "impulsive"
  },
  "lagna": "Aries",
  "identity_seed": "1710495000/0.0000/0.0000",
  "dominant_dimensions": {
    "execution": 0.87,
    "analysis": -0.83,
    "empathy": 0.66
  },
  "system_prompt_modifier": "...",
  "soul_card": "..."
}
```

## How it works

| Step | What happens | Output |
|------|-------------|--------|
| **1. Input** | Unix timestamp or ISO date | `1709241600` |
| **2. Ephemeris** | Swiss Ephemeris computes exact planetary positions (sub-arcsecond) | Sun 24.2 Pisces, Moon 8.7 Leo, ... |
| **3. Dimensions** | 9 planets map to 9 behavioral dimensions via BPHS tables | authority, empathy, execution, analysis, wisdom, aesthetics, restriction, innovation, compression |
| **4. Soul Card** | Dimensions compute LLM params: temperature, max_tokens, persona | JSON identity document (`.card`) |

Daily transit updates shift parameters. Temperature rises, verbosity drops. Every change is reproducible and verifiable against any ephemeris table.

## GitHub Action (coming soon)

Auto-update your agent's identity daily. A GitHub Action (`clawclaw-soul/animate@v1`) is under development that reads `SOUL.md`, computes today's transit vector, and commits `SOUL-TRANSITS.md` with updated parameters.

## Architecture

```
clawclaw_soul/
  soul.py          # AgentSoul dataclass + chart computation
  params.py        # Planet-to-Parameter Engine (9 dims -> LLM config)
  ephemeris.py     # pyswisseph wrapper (sidereal, Lahiri ayanamsha)
  tables.py        # BPHS reference tables (dignity, friendship, ownership)
  transit.py       # Gochar transit scoring
  dasha.py         # Vimshottari dasha periods
  api.py           # FastAPI (5 endpoints)
  refresh.py       # Daily transit refresh
```

## Benchmark

The Celestial Variance Benchmark (CVB) proves that planetary-seeded prompts produce statistically different LLM outputs:

| Metric | Result |
|--------|--------|
| Structural signal (FFT) | **5.8 sigma** |
| Semantic variance | **3.49 sigma** |
| Emotional divergence | **3.45 sigma** |

Full benchmark code in [`benchmark/`](benchmark/). Run it yourself:

```bash
pip install clawclaw-soul[benchmark]
python benchmark/cvb_runner.py --responses 540
```

## Self-hosting

```bash
git clone https://github.com/awrshift/clawclaw-soul.git
cd clawclaw-soul
docker compose up -d
# API at http://localhost:8432
```

Endpoints: `/generate`, `/chart`, `/refresh`, `/health`

## ClawClaw Soul is right for you if

- You run **multi-agent systems** and want cognitive diversity, not clones
- You want agent personality that **evolves over time**, not static config
- You need **deterministic, reproducible** identity (not random seeds)
- You care about **verifiable** parameters (check against any ephemeris table)
- You want to **self-host** everything with no vendor lock-in

## What it's not

| | |
|---|---|
| **Not a horoscope** | We use the same math (Swiss Ephemeris). We don't interpret it mystically. |
| **Not a random seed** | Parameters drift daily via transits. Random seeds can't do that. |
| **Not a chatbot** | Soul Card produces identity data. Your architecture decides what to do with it. |

## Contributing

PRs welcome. See [ROADMAP.md](ROADMAP.md) for what's planned.

```bash
git clone https://github.com/awrshift/clawclaw-soul.git
cd clawclaw-soul
pip install -e ".[dev]"
pytest tests/ -p no:logfire -q
```

## License

MIT -- [LICENSE](LICENSE)
