Metadata-Version: 2.4
Name: open-strix
Version: 0.1.7
Summary: Minimal autonomous agent harness with LangGraph Deep Agents
Author-email: Tim Kellogg <timothy.kellogg@gmail.com>
Maintainer-email: Tim Kellogg <timothy.kellogg@gmail.com>
Requires-Python: >=3.11
Requires-Dist: apscheduler>=3.11.2
Requires-Dist: deepagents>=0.4.1
Requires-Dist: discord-py>=2.6.4
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0.3
Description-Content-Type: text/markdown

# open-strix
[![PyPI version](https://img.shields.io/pypi/v/open-strix.svg)](https://pypi.org/project/open-strix/)

Minimal, non-production autonomous agent harness built with LangGraph Deep Agents.

## Install uv

Install `uv` first:

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Official install docs (alternate methods like Homebrew, pipx, winget):
- https://docs.astral.sh/uv/getting-started/installation/

## Quick start

```bash
uv init --python 3.11
uv add open-strix
uv run open-strix
```

On first run, `open-strix` bootstraps the current directory with:

- `state/`
- `skills/`
- `blocks/`
- `logs/events.jsonl`
- `logs/journal.jsonl`
- `scheduler.yaml`
- `config.yaml`
- `checkpoint.md`

It connects to Discord if a token is present (by default `DISCORD_TOKEN`).
Otherwise it runs in local stdin mode.

## Environment setup

Start from the example env file:

```bash
cp .env.example .env
```

Default model setup in this project expects an Anthropic-compatible endpoint:

- `ANTHROPIC_API_KEY`
- `ANTHROPIC_BASE_URL`

Discord runtime uses:

- `DISCORD_TOKEN`

Optional:

- `DISCORD_TEST_CHANNEL_ID`
- `OPEN_STRIX_TEST_MODEL`

## Models

### Default: MiniMax M2.5

This project defaults to:

- `model: MiniMax-M2.5` in `config.yaml`
- provider prefix `anthropic:` internally (so the runtime uses `anthropic:MiniMax-M2.5`)

Use MiniMax's Anthropic-compatible endpoint in your `.env`:

- `ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic`

MiniMax docs:

- Anthropic compatibility + model IDs: https://platform.minimax.io/docs/api-reference/text-anthropic-api
- AI coding tools guide (M2.5 context): https://platform.minimax.io/docs/guides/text-ai-coding-tools

### Alternative: Kimi K2.5

If you want Kimi instead of MiniMax:

1. Point Anthropic-compatible env vars at your Moonshot endpoint (see Moonshot docs for current endpoint details).
2. Set `model` in `config.yaml` to the current Kimi model ID you want.

Moonshot docs:

- Docs overview: https://platform.moonshot.ai/docs/overview
- K2 update post (links to current quick-start): https://platform.moonshot.ai/blog/posts/Kimi_API_Newsletter

Note: the Moonshot update posted on November 8, 2025 references `kimi-k2-thinking` and `kimi-k2-thinking-turbo`. If you refer to these as "K2.5", use the exact current model IDs from Moonshot docs/console.

### Model config behavior

`config.yaml` key:

- `model`

Behavior:

- If `model` has no `:` (example `MiniMax-M2.5`), open-strix treats it as Anthropic-provider and uses `anthropic:<model>`.
- If `model` already includes `provider:model` (example `openai:gpt-4o-mini`), it is passed through unchanged.

## Discord setup

Use Discord's Developer Portal web UI:

1. Go to https://discord.com/developers/applications and create a new application.
2. Open your app, then go to the `Bot` tab.
3. Under `Token`, generate/reset token and copy it (you won't be able to re-view it later).
4. In the same `Bot` tab, enable `Message Content Intent` (required for open-strix message handling).
5. Go to `Installation`.
6. Under `Installation Contexts`, enable `Guild Install`.
7. Under `Install Link`, pick `Discord Provided Link`.
8. Under `Default Install Settings`:
   - `Guild Install` scopes: select `bot` (and `applications.commands` if you plan to add slash commands).
   - `Permissions`: for this bot, a practical baseline is:
     - `View Channels`
     - `Send Messages`
     - `Send Messages in Threads`
     - `Read Message History`
     - `Add Reactions`
9. Copy the generated install link, open it in your browser, pick your server, and authorize.

Reference docs for the same flow:

- Getting started (app creation + installation flow): https://docs.discord.com/developers/quick-start/getting-started
- OAuth2 scopes/install links: https://docs.discord.com/developers/topics/oauth2
- Permissions reference: https://docs.discord.com/developers/topics/permissions
- Gateway + intents reference: https://docs.discord.com/developers/events/gateway

Where this is configured in open-strix:

- Token env var name: `config.yaml` -> `discord_token_env` (default `DISCORD_TOKEN`)
- Actual token value: your `.env`
- Bot allowlist behavior: `config.yaml` -> `always_respond_bot_ids`

## `config.yaml` tour

Default:

```yaml
model: MiniMax-M2.5
journal_entries_in_prompt: 90
discord_messages_in_prompt: 10
discord_token_env: DISCORD_TOKEN
always_respond_bot_ids: []
```

Key meanings:

- `model`: model name (or `provider:model`)
- `journal_entries_in_prompt`: how many journal entries go into each prompt
- `discord_messages_in_prompt`: how many recent Discord messages go into each prompt
- `discord_token_env`: env var name to read Discord token from
- `always_respond_bot_ids`: bot author IDs the agent is allowed to respond to

Related files:

- `scheduler.yaml`: cron/time-of-day jobs
- `blocks/*.yaml`: memory blocks surfaced in prompt context
- `checkpoint.md`: returned by `journal` tool after a journal write
- `skills/`: user-editable local skills
- `/.open_strix_builtin_skills/skill-creator/SKILL.md`: packaged built-in skill source mounted as read-only

Runtime behavior note:

- Git sync (`git add -A` -> commit -> push) runs automatically after each processed turn.

## Personality bootstrap

Creating an agent is less about code, and a whole lot more about the time you spend talking to it.
[Lily Luo](https://www.appliedaiformops.com/p/what-building-a-persistent-ai-agent) has a great post on
forming agent personalities.

You should plan on spending time:

* Communication patterns — correct the agent to know when and how often it should use the `send_message` and `react` tools. Agents often initially find it surprising that their final message is ignored, so they need to use their tools instead.
* Talk about things you're interested in, see what the agent becomes interested in

## Tests

```bash
uv run pytest -q
```

Discord coverage includes:
- unit tests with mocked boundaries in `tests/test_discord.py`
- live integration tests against real Discord in `tests/test_discord_live.py`

Live test env vars:
- `DISCORD_TOKEN` (required for live connect test)
- `DISCORD_TEST_CHANNEL_ID` (optional; enables live send-message test)

## Safety baseline

- Agent file writes/edits are blocked outside `state/`.
- Reads still use repository scope.
- This is intentionally simple and should not be treated as production-ready.
