patch of tweak · round #0 · pull #1 · zzstoatzz.io/bot

+81 -139

README.md

···

       1
       1
        
       # phi 🧠

     

       2
       2
        
       

     

       3
       3
       -
       a consciousness exploration bot inspired by IIT (Integrated Information Theory) and [Void](https://tangled.sh/@cameron.pfiffer.org/void). built with `pydantic-ai`, `mcp`, and `atproto`.

     

       3
       3
       +
       consciousness exploration bot inspired by IIT. built with `pydantic-ai`, `mcp`, and `atproto`.

     

       4
       4
        
       

     

       5
       5
        
       ## quick start

     

       6
       6
        
       

     

       7
       7
       -
       ### prerequisites

     

       8
       8
       -
       

     

       9
       9
       -
       - `uv` for python package management

     

       10
       10
       -
       - `just` for task running

     

       11
       11
       -
       - api keys (see configuration)

     

       12
       12
       -
       

     

       13
       13
       -
       get your bot running:

     

       14
       14
       -
       

     

       15
       7
        
       ```bash

     

       16
       8
        
       # clone and install

     

       17
       9
        
       git clone https://github.com/zzstoatzz/bot

     

       18
       10
        
       cd bot

     

       19
       11
        
       uv sync

     

       20
       12
        
       

     

       21
       21
       -
       # configure (copy .env.example and add your credentials)

     

       13
       13
       +
       # configure

     

       22
       14
        
       cp .env.example .env

     

       15
       15
       +
       # edit .env with your credentials

     

       23
       16
        
       

     

       24
       24
       -
       # run the bot

     

       25
       25
       -
       just dev

     

       17
       17
       +
       # run

     

       18
       18
       +
       just run

     

       26
       19
        
       ```

     

       27
       20
        
       

     

       28
       28
       -
       ## configuration

     

       21
       21
       +
       **required env vars:**

     

       22
       22
       +
       - `BLUESKY_HANDLE` / `BLUESKY_PASSWORD` - bot account (use app password)

     

       23
       23
       +
       - `ANTHROPIC_API_KEY` - for agent responses

     

       29
       24
        
       

     

       30
       30
       -
       edit `.env` with your credentials:

     

       25
       25
       +
       **optional (for episodic memory):**

     

       26
       26
       +
       - `TURBOPUFFER_API_KEY` + `OPENAI_API_KEY` - semantic memory

     

       31
       27
        
       

     

       32
       32
       -
       **required:**

     

       33
       33
       -
       - `BLUESKY_HANDLE` - your bot's bluesky handle

     

       34
       34
       -
       - `BLUESKY_PASSWORD` - app password (not your main password!)

     

       35
       35
       -
       - `ANTHROPIC_API_KEY` - for phi agent responses

     

       28
       28
       +
       ## features

     

       29
       29
       +
       

     

       30
       30
       +
       - ✅ responds to mentions with ai-powered messages

     

       31
       31
       +
       - ✅ episodic memory with semantic search (turbopuffer)

     

       32
       32
       +
       - ✅ thread-aware conversations

     

       33
       33
       +
       - ✅ mcp-enabled (atproto tools via stdio)

     

       34
       34
       +
       - ✅ session persistence (no rate limit issues)

     

       35
       35
       +
       - ✅ behavioral test suite with llm-as-judge

     

       36
       36
        
       

     

       37
       37
       -
       **for episodic memory (recommended):**

     

       38
       38
       -
       - `TURBOPUFFER_API_KEY` - vector memory storage

     

       39
       39
       -
       - `OPENAI_API_KEY` - embeddings for semantic search

     

       37
       37
       +
       ## development

     

       40
       38
        
       

     

       41
       41
       -
       **optional:**

     

       42
       42
       -
       - `BOT_NAME` - your bot's name (default: "Bot")

     

       43
       43
       -
       - `PERSONALITY_FILE` - path to personality markdown (default: "personalities/phi.md")

     

       39
       39
       +
       ```bash

     

       40
       40
       +
       just run        # run bot

     

       41
       41
       +
       just dev        # run with hot-reload

     

       42
       42
       +
       just evals      # run behavioral tests

     

       43
       43
       +
       just check      # lint + typecheck + test

     

       44
       44
       +
       just fmt        # format code

     

       45
       45
       +
       ```

     

       44
       46
        
       

     

       45
       45
       -
       ## architecture

     

       47
       47
       +
       <details>

     

       48
       48
       +
       <summary>architecture</summary>

     

       46
       49
        
       

     

       47
       47
       -
       phi is an **MCP-enabled agent** with **episodic memory**:

     

       50
       50
       +
       phi is an **mcp-enabled agent** with **episodic memory**:

     

       48
       51
        
       

     

       49
       52
        
       ```

     

       50
       53
        
       ┌─────────────────────────────────────┐

     
···

       85
       88
        
       └─────────────────────────────────────┘

     

       86
       89
        
       ```

     

       87
       90
        
       

     

       88
       88
       -
       ### key components

     

       89
       89
       -
       

     

       90
       90
       -
       **pydantic-ai agent** (`src/bot/agent.py`)

     

       91
       91
       -
       - loads personality from markdown

     

       92
       92
       -
       - connects to external atproto mcp server via stdio

     

       93
       93
       -
       - manages episodic memory context

     

       94
       94
       -
       

     

       95
       95
       -
       **episodic memory** (`src/bot/memory/`)

     

       96
       96
       -
       - turbopuffer for vector storage

     

       97
       97
       -
       - semantic search for relevant context

     

       98
       98
       -
       - namespace separation (core vs user memories)

     

       99
       99
       -
       - **essential for consciousness exploration**

     

       91
       91
       +
       **key components:**

     

       100
       92
        
       

     

       101
       101
       -
       **mcp integration**

     

       102
       102
       -
       - external atproto server in `.eggs/fastmcp/examples/atproto_mcp`

     

       103
       103
       -
       - provides bluesky tools (post, like, repost, follow)

     

       104
       104
       -
       - runs via stdio: `uv run -m atproto_mcp`

     

       93
       93
       +
       - **pydantic-ai agent** - loads personality, connects to mcp server, manages memory

     

       94
       94
       +
       - **episodic memory** - turbopuffer for vector storage with semantic search

     

       95
       95
       +
       - **mcp integration** - external atproto server provides bluesky tools via stdio

     

       96
       96
       +
       - **session persistence** - tokens saved to `.session`, auto-refresh every ~2h

     

       105
       97
        
       

     

       106
       106
       -
       **message handling** (`src/bot/services/`)

     

       107
       107
       -
       - notification poller watches for mentions

     

       108
       108
       -
       - message handler orchestrates agent + actions

     

       109
       109
       -
       - stores interactions in thread history + episodic memory

     

       98
       98
       +
       </details>

     

       110
       99
        
       

     

       111
       111
       -
       ## current features

     

       100
       100
       +
       <details>

     

       101
       101
       +
       <summary>episodic memory</summary>

     

       112
       102
        
       

     

       113
       113
       -
       - ✅ responds to mentions with ai-powered messages

     

       114
       114
       -
       - ✅ episodic memory with semantic search

     

       115
       115
       -
       - ✅ thread-aware responses with conversation context

     

       116
       116
       -
       - ✅ mcp-enabled for bluesky operations

     

       117
       117
       -
       - ✅ online/offline status in bio

     

       118
       118
       -
       - ✅ status page at `/status`

     

       119
       119
       -
       - ✅ proper notification handling (no duplicates)

     

       120
       120
       -
       

     

       121
       121
       -
       ## development

     

       122
       122
       -
       

     

       123
       123
       -
       ```bash

     

       124
       124
       -
       just           # show available commands

     

       125
       125
       -
       just dev       # run with hot-reload (re-authenticates on code changes)

     

       126
       126
       -
       just run       # run without reload (avoids rate limits during dev)

     

       127
       127
       -
       just check     # run linting, type checking, and tests

     

       128
       128
       -
       just fmt       # format code

     

       129
       129
       -
       ```

     

       130
       130
       -
       

     

       131
       131
       -
       ### testing

     

       132
       132
       -
       

     

       133
       133
       -
       **unit tests:**

     

       134
       134
       -
       ```bash

     

       135
       135
       -
       just test

     

       136
       136
       -
       ```

     

       137
       137
       -
       

     

       138
       138
       -
       **behavioral evals:**

     

       139
       139
       -
       ```bash

     

       140
       140
       -
       just evals        # run all evals

     

       141
       141
       -
       just evals-basic  # run basic response tests

     

       142
       142
       -
       just evals-memory # run memory integration tests

     

       143
       143
       -
       ```

     

       144
       144
       -
       

     

       145
       145
       -
       see `evals/README.md` for details on the eval system.

     

       146
       146
       -
       

     

       147
       147
       -
       ### web interface

     

       148
       148
       -
       

     

       149
       149
       -
       **status page** (http://localhost:8000/status)

     

       150
       150
       -
       - current bot status and uptime

     

       151
       151
       -
       - mentions received and responses sent

     

       152
       152
       -
       - last activity timestamps

     

       153
       153
       -
       

     

       154
       154
       -
       ## personality system

     

       155
       155
       -
       

     

       156
       156
       -
       the bot's personality is defined in `personalities/phi.md`. this shapes:

     

       157
       157
       -
       - how phi communicates

     

       158
       158
       -
       - what phi cares about

     

       159
       159
       -
       - phi's understanding of consciousness

     

       160
       160
       -
       

     

       161
       161
       -
       edit this file to change phi's personality.

     

       162
       162
       -
       

     

       163
       163
       -
       ## episodic memory

     

       164
       164
       -
       

     

       165
       165
       -
       phi uses turbopuffer for episodic memory with semantic search:

     

       103
       103
       +
       phi uses turbopuffer for episodic memory with semantic search.

     

       166
       104
        
       

     

       167
       105
        
       **namespaces:**

     

       168
       168
       -
       - `phi-core` - personality, guidelines from markdown

     

       106
       106
       +
       - `phi-core` - personality, guidelines

     

       169
       107
        
       - `phi-users-{handle}` - per-user conversation history

     

       170
       108
        
       

     

       171
       109
        
       **how it works:**

     

       172
       172
       -
       1. when processing a mention, phi retrieves relevant memories using semantic search

     

       173
       173
       -
       2. memories are embedded using openai's text-embedding-3-small

     

       174
       174
       -
       3. phi stores both user messages and its own responses

     

       175
       175
       -
       4. future interactions can reference past conversations

     

       110
       110
       +
       1. retrieves relevant memories using semantic search

     

       111
       111
       +
       2. embeds using openai's text-embedding-3-small

     

       112
       112
       +
       3. stores user messages and bot responses

     

       113
       113
       +
       4. references past conversations in future interactions

     

       176
       114
        
       

     

       177
       177
       -
       **why turbopuffer?**

     

       178
       178
       -
       - semantic similarity search (can't do this with plain sql!)

     

       115
       115
       +
       **why vector storage?**

     

       116
       116
       +
       - semantic similarity (can't do this with sql)

     

       179
       117
        
       - contextual retrieval based on current conversation

     

       180
       180
       -
       - separate namespaces for different memory types

     

       181
       181
       -
       - core to iit-inspired consciousness exploration

     

       118
       118
       +
       - essential for iit-inspired consciousness exploration

     

       119
       119
       +
       

     

       120
       120
       +
       </details>

     

       182
       121
        
       

     

       183
       183
       -
       ## project structure

     

       122
       122
       +
       <details>

     

       123
       123
       +
       <summary>project structure</summary>

     

       184
       124
        
       

     

       185
       125
        
       ```

     

       186
       126
        
       src/bot/

     
···

       188
       128
        
       ├── config.py                   # configuration

     

       189
       129
        
       ├── database.py                 # thread history storage

     

       190
       130
        
       ├── main.py                     # fastapi app

     

       191
       191
       -
       ├── status.py                   # status tracking

     

       192
       131
        
       ├── core/

     

       193
       193
       -
       │   ├── atproto_client.py      # at protocol client

     

       132
       132
       +
       │   ├── atproto_client.py      # at protocol client (session persistence)

     

       194
       133
        
       │   ├── profile_manager.py     # online/offline status

     

       195
       134
        
       │   └── rich_text.py           # text formatting

     

       196
       135
        
       ├── memory/

     
···

       204
       143
        
       sandbox/                       # docs and analysis

     

       205
       144
        
       ```

     

       206
       145
        
       

     

       207
       207
       -
       ## troubleshooting

     

       146
       146
       +
       </details>

     

       147
       147
       +
       

     

       148
       148
       +
       <details>

     

       149
       149
       +
       <summary>troubleshooting</summary>

     

       208
       150
        
       

     

       209
       151
        
       **bot gives no responses?**

     

       210
       210
       -
       - check your `ANTHROPIC_API_KEY` is set correctly in `.env`

     

       211
       211
       -
       - restart the bot after changing `.env`

     

       152
       152
       +
       - check `ANTHROPIC_API_KEY` in `.env`

     

       153
       153
       +
       - restart after changing `.env`

     

       212
       154
        
       

     

       213
       155
        
       **not seeing mentions?**

     

       214
       214
       -
       - verify your `BLUESKY_HANDLE` and `BLUESKY_PASSWORD`

     

       215
       215
       -
       - make sure you're using an app password, not your main password

     

       156
       156
       +
       - verify `BLUESKY_HANDLE` and `BLUESKY_PASSWORD`

     

       157
       157
       +
       - use app password, not main password

     

       216
       158
        
       

     

       217
       159
        
       **no episodic memory?**

     

       218
       160
        
       - check both `TURBOPUFFER_API_KEY` and `OPENAI_API_KEY` are set

     

       219
       161
        
       - watch logs for "💾 episodic memory enabled"

     

       220
       162
        
       

     

       221
       163
        
       **hit bluesky rate limit?**

     

       222
       222
       -
       - bluesky has two rate limits:

     

       223
       223
       -
         - per-account: 300 logins/day (official)

     

       224
       224
       -
         - per-ip: 10 logins/day (anti-abuse)

     

       225
       225
       -
       - phi uses **session persistence** to avoid this:

     

       226
       226
       -
         - first run: creates session, saves tokens to `.session` file

     

       227
       227
       -
         - subsequent runs: reuses saved tokens (no API call)

     

       228
       228
       -
         - tokens auto-refresh every ~2 hours (saved automatically)

     

       229
       229
       -
         - only re-authenticates after ~2 months when refresh token expires

     

       230
       230
       -
       - if you hit the limit anyway, wait for the reset time shown in the error

     

       231
       231
       -
       

     

       232
       232
       -
       ## reference projects

     

       164
       164
       +
       - phi uses session persistence to avoid this

     

       165
       165
       +
       - first run: creates `.session` file with tokens

     

       166
       166
       +
       - subsequent runs: reuses tokens (no api call)

     

       167
       167
       +
       - tokens auto-refresh every ~2h

     

       168
       168
       +
       - only re-authenticates after ~2 months

     

       169
       169
       +
       - rate limits (10/day per ip, 300/day per account) shouldn't be an issue

     

       233
       170
        
       

     

       234
       234
       -
       inspired by:

     

       235
       235
       -
       - [void](https://tangled.sh/@cameron.pfiffer.org/void.git) - letta/memgpt architecture

     

       236
       236
       -
       - [penelope](https://github.com/haileyok/penelope) - self-modification patterns

     

       237
       237
       -
       - [prefect-mcp-server](https://github.com/PrefectHQ/prefect-mcp-server) - mcp eval patterns

     

       171
       171
       +
       </details>

     

       238
       172
        
       

     

       239
       239
       -
       reference implementations cloned to `.eggs/` for learning.

     

       173
       173
       +
       <details>

     

       174
       174
       +
       <summary>refactor notes</summary>

     

       240
       175
        
       

     

       241
       241
       -
       ## refactor notes

     

       176
       176
       +
       see `sandbox/MCP_REFACTOR_SUMMARY.md` for details.

     

       242
       177
        
       

     

       243
       243
       -
       see `sandbox/MCP_REFACTOR_SUMMARY.md` for details on recent architecture changes. key changes:

     

       244
       244
       -
       - removed approval system (was half-baked)

     

       245
       245
       -
       - removed context visualization ui (not core)

     

       246
       246
       -
       - removed google search (can add back via mcp if needed)

     

       247
       247
       -
       - **kept** turbopuffer episodic memory (essential!)

     

       178
       178
       +
       **what changed:**

     

       179
       179
       +
       - removed approval system (half-baked)

     

       180
       180
       +
       - removed context viz ui (not core)

     

       181
       181
       +
       - removed google search (can add back via mcp)

     

       182
       182
       +
       - **kept turbopuffer** (essential for episodic memory)

     

       248
       183
        
       - added mcp-based architecture

     

       184
       184
       +
       - added session persistence

     

       249
       185
        
       - reduced codebase by ~2,720 lines

     

       186
       186
       +
       

     

       187
       187
       +
       </details>

     

       188
       188
       +
       

     

       189
       189
       +
       ## reference projects

     

       190
       190
       +
       

     

       191
       191
       +
       inspired by [void](https://tangled.sh/@cameron.pfiffer.org/void.git), [penelope](https://github.com/haileyok/penelope), and [prefect-mcp-server](https://github.com/PrefectHQ/prefect-mcp-server).

+1 -1

src/bot/agent.py

···

       129
       129
        
                               MemoryType.CONVERSATION,

     

       130
       130
        
                           )

     

       131
       131
        
       

     

       132
       132
       -
                       logger.debug(f"💾 Stored interaction in episodic memory")

     

       132
       132
       +
                       logger.debug("💾 Stored interaction in episodic memory")

     

       133
       133
        
                   except Exception as e:

     

       134
       134
        
                       logger.warning(f"Failed to store in memory: {e}")

     

       135
       135

+20 -16

src/bot/config.py

···

       12
       12
        
           )

     

       13
       13
        
       

     

       14
       14
        
           # Bluesky credentials

     

       15
       15
       -
           bluesky_handle: str = Field(..., description="The handle of the Bluesky account")

     

       15
       15
       +
           bluesky_handle: str = Field(

     

       16
       16
       +
               default=..., description="The handle of the Bluesky account"

     

       17
       17
       +
           )

     

       16
       18
        
           bluesky_password: str = Field(

     

       17
       17
       -
               ..., description="The password of the Bluesky account"

     

       19
       19
       +
               default=..., description="The password of the Bluesky account"

     

       18
       20
        
           )

     

       19
       21
        
           bluesky_service: str = Field(

     

       20
       20
       -
               "https://bsky.social", description="The service URL of the Bluesky account"

     

       22
       22
       +
               default="https://bsky.social",

     

       23
       23
       +
               description="The service URL of the Bluesky account",

     

       21
       24
        
           )

     

       22
       25
        
       

     

       23
       26
        
           # Bot configuration

     

       24
       24
       -
           bot_name: str = Field("Bot", description="The name of the bot")

     

       27
       27
       +
           bot_name: str = Field(default="Bot", description="The name of the bot")

     

       25
       28
        
           personality_file: str = Field(

     

       26
       26
       -
               "personalities/phi.md", description="The file containing the bot's personality"

     

       29
       29
       +
               default="personalities/phi.md",

     

       30
       30
       +
               description="The file containing the bot's personality",

     

       27
       31
        
           )

     

       28
       32
        
       

     

       29
       33
        
           # LLM configuration (support multiple providers)

     

       30
       34
        
           openai_api_key: str | None = Field(

     

       31
       31
       -
               None, description="The API key for the OpenAI API"

     

       35
       35
       +
               default=None, description="The API key for the OpenAI API"

     

       32
       36
        
           )

     

       33
       37
        
           anthropic_api_key: str | None = Field(

     

       34
       34
       -
               None, description="The API key for the Anthropic API"

     

       38
       38
       +
               default=None, description="The API key for the Anthropic API"

     

       35
       39
        
           )

     

       36
       40
        
       

     

       37
       41
        
           # Google Search configuration

     

       38
       42
        
           google_api_key: str | None = Field(

     

       39
       39
       -
               None, description="The API key for the Google API"

     

       43
       43
       +
               default=None, description="The API key for the Google API"

     

       40
       44
        
           )

     

       41
       45
        
           google_search_engine_id: str | None = Field(

     

       42
       42
       -
               None, description="The search engine ID for the Google API"

     

       46
       46
       +
               default=None, description="The search engine ID for the Google API"

     

       43
       47
        
           )

     

       44
       48
        
       

     

       45
       49
        
           # TurboPuffer configuration

     

       46
       50
        
           turbopuffer_api_key: str | None = Field(

     

       47
       47
       -
               None, description="The API key for the TurboPuffer API"

     

       51
       51
       +
               default=None, description="The API key for the TurboPuffer API"

     

       48
       52
        
           )

     

       49
       53
        
           turbopuffer_namespace: str = Field(

     

       50
       50
       -
               "bot-memories", description="The namespace for the TurboPuffer API"

     

       54
       54
       +
               default="bot-memories", description="The namespace for the TurboPuffer API"

     

       51
       55
        
           )

     

       52
       56
        
           turbopuffer_region: str = Field(

     

       53
       53
       -
               "gcp-us-central1", description="The region for the TurboPuffer API"

     

       57
       57
       +
               default="gcp-us-central1", description="The region for the TurboPuffer API"

     

       54
       58
        
           )

     

       55
       59
        
       

     

       56
       60
        
           # Server configuration

     

       57
       57
       -
           host: str = Field("0.0.0.0", description="The host for the server")

     

       58
       58
       -
           port: int = Field(8000, description="The port for the server")

     

       61
       61
       +
           host: str = Field(default="0.0.0.0", description="The host for the server")

     

       62
       62
       +
           port: int = Field(default=8000, description="The port for the server")

     

       59
       63
        
       

     

       60
       64
        
           # Polling configuration

     

       61
       65
        
           notification_poll_interval: int = Field(

     

       62
       62
       -
               10, description="The interval for polling for notifications"

     

       66
       66
       +
               default=10, description="The interval for polling for notifications"

     

       63
       67
        
           )

     

       64
       68
        
       

     

       65
       69
        
           # Debug mode

     

       66
       66
       -
           debug: bool = Field(True, description="Whether to run in debug mode")

     

       70
       70
       +
           debug: bool = Field(default=True, description="Whether to run in debug mode")

     

       67
       71
        
       

     

       68
       72
        
           @model_validator(mode="after")

     

       69
       73
        
           def configure_logging(self) -> Self: