Metadata-Version: 2.4
Name: isa-mate
Version: 0.2.0
Summary: isA Mate - The default agent app of the isA platform
Project-URL: Homepage, https://github.com/xenoISA/isA_Mate
Project-URL: Repository, https://github.com/xenoISA/isA_Mate
Project-URL: Issues, https://github.com/xenoISA/isA_Mate/issues
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: croniter>=2.0.0
Requires-Dist: docker>=7.0.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: isa-agent-sdk>=0.3.3
Requires-Dist: isa-common>=0.6.0
Requires-Dist: isa-model>=0.6.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: packaging>=23.0
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: redis>=5.0.0
Requires-Dist: sse-starlette>=1.6.5
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: websockets>=12.0
Provides-Extra: channels
Requires-Dist: discord-py>=2.0; extra == 'channels'
Requires-Dist: python-telegram-bot>=20.0; extra == 'channels'
Provides-Extra: dev
Requires-Dist: cryptography>=41.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: office
Requires-Dist: fpdf2>=2.8.0; extra == 'office'
Requires-Dist: openpyxl>=3.1.0; extra == 'office'
Requires-Dist: python-docx>=1.1.0; extra == 'office'
Requires-Dist: python-pptx>=0.6.23; extra == 'office'
Provides-Extra: sync
Requires-Dist: cryptography>=41.0; extra == 'sync'
Description-Content-Type: text/markdown

# isA Mate

The default agent app of the [isA platform](https://github.com/xenoISA). A personal AI companion that connects to any messaging platform and runs locally or in the cloud.

## Features

- **Multi-channel**: Telegram, Discord, Slack, WhatsApp, Feishu, Signal, Teams, Matrix (and more coming)
- **Multi-model**: Route through Anthropic, OpenAI, or local Ollama models
- **Multi-agent**: Hybrid A2A delegation across pinned platform teams and dynamically discovered org agents
- **Memory**: Persistent conversation memory with SQLite or remote backends
- **Tools**: 190+ tools via MCP (Model Context Protocol)
- **Local-first**: Runs on your machine with optional cloud deployment

## Quick Start

### Option A: pip install (recommended)

```bash
pip install isa-mate

# Interactive setup — picks your model provider, channels, etc.
isa-mate init

# Start the gateway server
isa-mate serve
```

### Option B: Docker (one command)

```bash
docker run -e ANTHROPIC_API_KEY=sk-... -p 18789:18789 ghcr.io/xenoisa/isa-mate
```

Or with Docker Compose for the full stack:

```bash
git clone https://github.com/xenoISA/isA_Mate.git && cd isA_Mate
echo "ANTHROPIC_API_KEY=sk-..." > .env
docker compose up
```

### Verify it's running

```bash
# Health check
curl http://localhost:18789/health

# Send a message
curl -X POST http://localhost:18789/v1/query \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Hello!"}'
```

## Requirements

- Python 3.10+ (pip install) or Docker
- An AI model provider (Ollama for free local models, or Anthropic/OpenAI subscription)
- If using a subscription provider (`anthropic-sub` / `codex-sub`):
  `SUBSCRIPTION_PROXY_URL` pointing at an `isa_model` deployment. The
  subscription proxy lives in `isa_model` since xenoISA/isA_Model#901 —
  Mate no longer starts it locally. See
  `docs/guides/subscription_proxy_migration.md` in the isa_model repo.

## Commands

| Command | Description |
|---------|-------------|
| `isa-mate init` | Interactive setup wizard |
| `isa-mate serve` | Start gateway server |
| `isa-mate cli` | Interactive terminal mode |
| `isa-mate query "..."` | One-shot query |
| `isa-mate doctor` | Run diagnostics |
| `isa-mate accounts` | Manage subscription accounts |

## Connecting Channels

After setup, connect your favorite messaging platform:

### Telegram

```bash
# 1. Create a bot via @BotFather, get your token
# 2. Set the token
export TELEGRAM_BOT_TOKEN=your-token-here

# 3. Start with Telegram enabled
isa-mate serve
```

### Discord

```bash
# 1. Create a Discord bot at https://discord.com/developers
# 2. Set the token
export DISCORD_BOT_TOKEN=your-token-here

# 3. Install the channels extra
pip install isa-mate[channels]

# 4. Start
isa-mate serve
```

### Slack

```bash
# 1. Create a Slack app at https://api.slack.com/apps
# 2. Set credentials
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_SIGNING_SECRET=your-secret

# 3. Start
isa-mate serve
```

See [Channel Integrations Guide](docs/channels.md) for all supported platforms.

## Configuration

Configuration is stored at `~/.isa/mate/config.yaml`. Run `isa-mate init` to generate it interactively, or use `--non-interactive` mode with environment variables:

```bash
ISA_MATE_MODEL=llama3 ISA_MATE_PROVIDER=ollama isa-mate init --non-interactive
```

Mate delegation supports a hybrid routing model:
- Pinned core teams from `teams.entries`
- Dynamic org-agent lookup from `teams.directory`
- Per-request shortlisting before the model decides whether to delegate

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ISA_MATE_HOST` | `127.0.0.1` | Gateway bind host |
| `ISA_MATE_PORT` | `18789` | Gateway bind port |
| `ISA_MATE_MODEL` | `gpt-5-nano` | Model name |
| `ISA_MATE_PROVIDER` | (empty) | Provider: `anthropic-sub`, `codex-sub`, `ollama` |
| `ISA_MATE_EXECUTION_MODE` | `reactive` | Agent execution mode |
| `ANTHROPIC_API_KEY` | (empty) | Anthropic API key (for Docker) |

## Deployment Modes

- **Local-first** (`isa-mate serve`): Run on your machine
- **Docker** (`docker compose up`): Containerized with health checks
- **Cloud** (`isa-mate cloud`): Headless cloud deployment
- **Pool** (`isa-mate pool`): Shared pool mode for multi-tenant setups

## isA Mate vs OpenClaw

| Capability | isA Mate | OpenClaw |
|------------|----------|----------|
| Setup | `pip install isa-mate && isa-mate init` | Clone repo + manual config |
| Docker | `docker run ... ghcr.io/xenoisa/isa-mate` | No official image |
| Channels | 8+ (Telegram, Discord, Slack, WhatsApp, ...) | API only |
| Multi-model | Anthropic, OpenAI, Ollama, local | Single provider |
| Multi-agent | Hybrid A2A delegation | Single agent |
| Tools | 190+ via MCP | Plugin-based |
| Memory | SQLite/remote with compaction | In-memory |
| Local-first | Yes — runs on your laptop | Server-only |

## License

MIT
