Metadata-Version: 2.4
Name: weasley-assistant
Version: 0.2.0
Summary: A transparent, local-first AI assistant with tools, memory, gateways, and evaluation.
Project-URL: Homepage, https://github.com/potatohoney-p/weasley-assistant
Project-URL: Repository, https://github.com/potatohoney-p/weasley-assistant
Project-URL: Issues, https://github.com/potatohoney-p/weasley-assistant/issues
Author: Weasley Contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-framework,ai-agent,eval,llm,llmops,local-first,memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.50
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Provides-Extra: discord
Requires-Dist: discord-py>=2.4; extra == 'discord'
Provides-Extra: eval
Requires-Dist: deepeval>=2.0; extra == 'eval'
Requires-Dist: pytest>=8.0; extra == 'eval'
Provides-Extra: gcal
Requires-Dist: google-api-python-client>=2.0; extra == 'gcal'
Requires-Dist: google-auth-httplib2>=0.2; extra == 'gcal'
Requires-Dist: google-auth-oauthlib>=1.0; extra == 'gcal'
Requires-Dist: google-auth>=2.0; extra == 'gcal'
Requires-Dist: httplib2>=0.22; extra == 'gcal'
Provides-Extra: mcp
Requires-Dist: jsonschema>=4.23; extra == 'mcp'
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: notion
Requires-Dist: notion-client>=2.5; extra == 'notion'
Provides-Extra: supabase
Requires-Dist: supabase>=2.0; extra == 'supabase'
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
Provides-Extra: tracing
Requires-Dist: arize-phoenix>=7.0; extra == 'tracing'
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'tracing'
Provides-Extra: voice
Requires-Dist: faster-whisper>=1.0; extra == 'voice'
Requires-Dist: numpy>=1.24; extra == 'voice'
Requires-Dist: sounddevice>=0.4; extra == 'voice'
Provides-Extra: voice-neural
Requires-Dist: kokoro>=0.9; extra == 'voice-neural'
Requires-Dist: soundfile>=0.12; extra == 'voice-neural'
Provides-Extra: whatsapp
Requires-Dist: httpx>=0.25; extra == 'whatsapp'
Description-Content-Type: text/markdown

# Weasley Assistant

![Weasley Assistant: local-first, transparent, extensible](https://raw.githubusercontent.com/potatohoney-p/weasley-assistant/main/assets/weasley-assistant-hero.png)

Weasley Assistant is a readable, local-first AI assistant for developers who want to own the
agent loop, tools, memory, gateways, and evaluation harness. Its public command and Python
package use the `weasley-assistant` / `weasley_assistant` names throughout.

## Features

- **Transparent agent loop:** model calls, tool results, iteration limits, and traces are explicit.
- **Layered memory:** SQLite-backed semantic and episodic memory plus file-based procedural skills.
- **Local dashboard:** inspect conversations, tools, memory, graph routes, traces, and evaluation.
- **Multiple gateways:** terminal, Telegram, Discord, WhatsApp, and optional local voice.
- **Model choice:** Anthropic, OpenAI, Gemini, DeepSeek, MiniMax, Kimi, GLM, OpenRouter, and
  compatible endpoints.
- **Safe extensibility:** opt-in Apple/Google integrations, read-only GitHub tools, MCP connectors,
  and deterministic regression tests.
- **Operations:** JSONL tracing, deterministic evaluation, optional LLM judging, and release gates.

## Requirements

- Python 3.11 or newer
- An API key for the provider you select
- Optional platform dependencies for voice and Apple integrations

## Installation

From PyPI:

```bash
python -m pip install weasley-assistant
```

For development:

```bash
git clone https://github.com/potatohoney-p/weasley-assistant.git
cd weasley-assistant
python -m venv .venv
python -m pip install -e ".[dev]"
```

Copy the environment template, add one provider key, and start the CLI:

```bash
cp .env.example .env
weasley-assistant
```

Common commands:

```bash
weasley-assistant dashboard
weasley-assistant brief
weasley-assistant gather
weasley-assistant voice
weasley-assistant skill install <skill-url>
```

`make run`, `make dashboard`, `make eval`, and the other Make targets are equivalent shortcuts.

## Configuration

Runtime state defaults to `~/.weasley/assistant`. Set configuration with the
`WEASLEY_ASSISTANT_*` namespace:

```dotenv
WEASLEY_ASSISTANT_PROVIDER=anthropic
WEASLEY_ASSISTANT_MODEL=
WEASLEY_ASSISTANT_SMALL_MODEL=
WEASLEY_ASSISTANT_HOME=~/.weasley/assistant
WEASLEY_ASSISTANT_MAX_ITERATIONS=10
WEASLEY_ASSISTANT_MAX_TOKENS=8192
WEASLEY_ASSISTANT_HISTORY_TURNS=12
```

Provider credentials keep their standard names, such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
or `GEMINI_API_KEY`. See [`.env.example`](.env.example) for all gateways and optional backends.

### Weasley namespace

Configuration, documentation, dashboard writes, and package imports use the
`WEASLEY_ASSISTANT_*`, `~/.weasley/assistant`, and `weasley_assistant` namespaces exclusively.

### MCP connectors

Install the optional dependency and create `~/.weasley/assistant/mcp.json`:

```bash
python -m pip install "weasley-assistant[mcp]"
```

```json
{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/safe/path"],
      "env": {}
    }
  ]
}
```

The file is validated against [`weasley_assistant/tools/mcp.schema.json`](weasley_assistant/tools/mcp.schema.json) before a
connector thread starts. Server failures are isolated, and all sessions and the event-loop thread
are closed when the assistant is rebuilt or stopped.

## Project structure

| Area | Location |
|---|---|
| Public package and CLI | [`weasley_assistant/`](weasley_assistant) |
| Agent loop and providers | [`weasley_assistant/loop/`](weasley_assistant/loop) |
| Memory | [`weasley_assistant/memory/`](weasley_assistant/memory) |
| Tools and MCP | [`weasley_assistant/tools/`](weasley_assistant/tools) |
| Gateways | [`weasley_assistant/gateway/`](weasley_assistant/gateway) |
| Dashboard and evaluation ops | [`weasley_assistant/ops/`](weasley_assistant/ops), [`evals/`](evals) |
| Procedural skills | [`skills/`](skills) |

## Security

- The dashboard binds to `127.0.0.1` by default.
- Runtime state, OAuth material, tokens, and local environment files are git-ignored.
- Discord server channels are deny-by-default until explicitly allowlisted.
- WhatsApp webhooks require signature verification.
- GitHub access is read-only by construction.
- MCP configuration is schema-validated before subprocesses start; each connector is isolated.
- Tool access and third-party gateways can incur API costs or mutate external systems. Enable only
  the integrations you understand and scope credentials to the minimum permissions required.

Please report vulnerabilities privately as described in [`SECURITY.md`](SECURITY.md). Do not put
credentials or exploit details in a public issue.

## Testing

```bash
python -m pytest -q evals/deterministic
python -m ruff check weasley_assistant evals scripts
```

Judge-based evaluations are optional and require provider credentials:

```bash
python -m pytest -q evals/judge
```

## Contributing

Read [`CONTRIBUTING.md`](CONTRIBUTING.md), add deterministic tests for behavior changes, and keep
optional integrations fail-safe when dependencies or credentials are absent. Issues and pull
requests are tracked at
[`potatohoney-p/weasley-assistant`](https://github.com/potatohoney-p/weasley-assistant).

## License

Apache License 2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
