Metadata-Version: 2.4
Name: neuralclaw
Version: 0.6.5
Summary: The Self-Evolving Cognitive Agent Framework
Author-email: Mirac <mirac@cardify.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/placeparks/neuralclaw
Project-URL: Repository, https://github.com/placeparks/neuralclaw
Project-URL: Issues, https://github.com/placeparks/neuralclaw/issues
Project-URL: Documentation, https://github.com/placeparks/neuralclaw/tree/main/docs
Keywords: ai,agent,cognitive,autonomous,llm,self-evolving,multi-channel,framework
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: toml>=0.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: aiosqlite>=0.19
Requires-Dist: keyring>=25.0
Requires-Dist: playwright>=1.52
Requires-Dist: python-telegram-bot>=21.0
Requires-Dist: discord.py>=2.3
Requires-Dist: slack-bolt>=1.18
Requires-Dist: qrcode>=7.4
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3; extra == "discord"
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18; extra == "slack"
Provides-Extra: sessions
Requires-Dist: playwright>=1.52; extra == "sessions"
Provides-Extra: all-channels
Requires-Dist: python-telegram-bot>=21.0; extra == "all-channels"
Requires-Dist: discord.py>=2.3; extra == "all-channels"
Requires-Dist: slack-bolt>=1.18; extra == "all-channels"
Provides-Extra: all
Requires-Dist: python-telegram-bot>=21.0; extra == "all"
Requires-Dist: discord.py>=2.3; extra == "all"
Requires-Dist: slack-bolt>=1.18; extra == "all"
Requires-Dist: playwright>=1.52; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Dynamic: license-file

# NeuralClaw

NeuralClaw is a Python agent framework with:

- multi-provider LLM routing
- direct ChatGPT and Claude browser-session support
- multi-channel messaging adapters
- memory, reasoning, policy, and tool execution layers
- simple channel trust modes: `open`, `pair`, `bound`

## Install

```bash
# PyPI install with all built-in Python dependencies
pip install neuralclaw

# Local checkout
pip install .

# Development
pip install -e ".[dev]"

# Compatibility aliases for older setup flows
pip install -e ".[sessions]"
pip install -e ".[all-channels]"
pip install -e ".[all,dev]"
```

`pip install neuralclaw` now installs the Python packages needed for all built-in
providers and channel adapters. Some integrations still need external runtimes:

- Playwright browser binaries for `chatgpt_app` and `claude_app`
- Node.js for the WhatsApp bridge
- `signal-cli` for Signal

Install Playwright browsers with:

```bash
python -m playwright install chromium
```

## Quick Start

```bash
# Create config and set API-backed providers
neuralclaw init

# Configure a direct ChatGPT browser session
neuralclaw session setup chatgpt

# Or configure a direct Claude browser session
neuralclaw session setup claude

# Configure channel credentials
neuralclaw channels setup

# Check status
neuralclaw status
neuralclaw session status

# Interactive chat
neuralclaw chat

# Force a specific provider
neuralclaw chat -p proxy
neuralclaw chat -p chatgpt_app
neuralclaw chat -p claude_app

# Start gateway with channels + web chat
neuralclaw gateway
```

## Providers

NeuralClaw supports these provider types:

| Provider | Purpose | Setup |
|---|---|---|
| `openai` | Official OpenAI API | `neuralclaw init` |
| `anthropic` | Official Anthropic API | `neuralclaw init` |
| `openrouter` | OpenRouter API | `neuralclaw init` |
| `proxy` | OpenAI-compatible relay | `neuralclaw proxy setup` |
| `chatgpt_app` | Direct ChatGPT browser session | `neuralclaw session setup chatgpt` |
| `claude_app` | Direct Claude browser session | `neuralclaw session setup claude` |
| `local` | Local OpenAI-compatible endpoint | set in config |

Notes:

- `chatgpt_app` and `claude_app` use managed persistent browser profiles.
- App-session providers are text-first and may fall back to tool-capable providers when tool calls are required.
- `proxy` remains useful for self-hosted relays or API-normalized session bridges.

## Channel Trust

Each channel can run in one of three trust modes:

| Mode | Behavior |
|---|---|
| `open` | Always accept inbound messages |
| `pair` | Require one-time `/pair` in that route before trusting it |
| `bound` | Only trusted bindings can talk; `/pair` creates the initial binding |

Default behavior:

- local web / CLI routes behave like `open`
- private messaging routes behave like `pair`
- shared routes behave like `bound`

Trusted bindings are stored locally in `~/.neuralclaw/data/channel_bindings.json`.

## Session Commands

```bash
neuralclaw session setup chatgpt
neuralclaw session setup claude
neuralclaw session status
neuralclaw session login chatgpt
neuralclaw session login claude
neuralclaw session repair chatgpt
neuralclaw session repair claude
```

## Project Layout

```text
neuralclaw/
  bus/         event bus and telemetry
  channels/    Telegram, Discord, Slack, Signal, WhatsApp, Web, trust layer
  cortex/      perception, memory, reasoning, action, evolution
  providers/   API providers, proxy provider, app-session providers, router
  session/     managed browser session runtime
  skills/      tool registry and built-ins
  gateway.py   orchestration entrypoint
  cli.py       command-line interface
  config.py    config, secrets, provider/channel setup
```

## Test

```bash
pytest -q
python -m compileall neuralclaw
python -m build
```

## Docs

See:

- [docs/channels.md](docs/channels.md)
- [docs/configuration.md](docs/configuration.md)
- [docs/security.md](docs/security.md)
