README.md

---
title: Second Brain Environment
emoji: 🧠
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 8000
---


# 🧠 Second Brain — OpenEnv Environment

> A Personal Knowledge Management environment where AI agents learn to capture, organize, and retrieve information — simulating the real-world challenge of managing a second brain.

[![OpenEnv](https://img.shields.io/badge/OpenEnv-compatible-blue)](https://github.com/meta-pytorch/OpenEnv)
[![HuggingFace](https://img.shields.io/badge/🤗-HuggingFace%20Space-yellow)](https://huggingface.co/spaces/RAc1928/second-brain-env)
[![Python](https://img.shields.io/badge/Python-3.10%2B-green)](https://python.org)

---

## 🌍 Motivation

Millions of people struggle with **information overload** daily. We save articles, capture meeting notes, jot down ideas — but rarely retrieve them when we actually need them. 

This environment trains AI agents to act as a **Personal Knowledge Manager**: capturing raw notes, organizing them correctly, and retrieving the right information at the right time. This is a genuine real-world skill that benefits students, professionals, researchers, and anyone who manages information.

---

## 🎯 Tasks

### Task 1 — `note_categorization` 🟢 Easy
| Property | Value |
|---|---|
| **Goal** | Assign each of 10 raw notes to the correct category |
| **Categories** | `work`, `personal`, `reference`, `action_item` |
| **Max Steps** | 12 |
| **Reward** | +0.10 per correct, -0.02 per wrong, 0.00 per skip |
| **Score Formula** | `correct_count / 10` |

### Task 2 — `memory_retrieval` 🟡 Medium
| Property | Value |
|---|---|
| **Goal** | Find the most relevant note in a 30-note KB for each of 5 questions |
| **Max Steps** | 15 |
| **Reward** | +0.20 exact match, +0.05–0.16 near miss, -0.05 miss, -0.10 repeated failure |
| **Score Formula** | `avg(retrieval_scores) / 5` |

### Task 3 — `knowledge_synthesis` 🔴 Hard
| Property | Value |
|---|---|
| **Goal** | Synthesize multi-theme insights from a 50-note knowledge base |
| **Max Steps** | 20 |
| **Reward** | Up to +0.35 per question (theme coverage + note coverage + length) |
| **Score Formula** | `avg(synthesis_scores) / 3` |

---

## 📐 Action Space

```python
class SecondBrainAction(BaseModel):
    action_type: str   # "categorize" | "retrieve" | "synthesize" | "tag" | "skip"
    content: str       # category name / search query / synthesized answer
    note_id: Optional[str]       # target note ID (optional)
    tags: Optional[List[str]]    # tags to apply (optional)
```

**Action types:**
- `categorize` — assign a category label to the current note (Task 1)
- `retrieve`   — search the knowledge base with a query string (Task 2 & 3)
- `synthesize` — produce a final synthesized answer (Task 3)
- `skip`       — skip the current item (no reward)

---

## 👁️ Observation Space

```python
class SecondBrainObservation(BaseModel):
    current_note: Optional[Dict]        # note being processed (Task 1)
    query: str                          # question to answer (Task 2 & 3)
    retrieved_notes: Optional[List]     # top notes from KB search
    knowledge_base_size: int            # total notes in KB
    step_count: int                     # current step
    task_name: str                      # active task
    reward: float                       # reward from last action
    done: bool                          # episode finished?
    score: float                        # running score in [0.0, 1.0]
    feedback: str                       # human-readable feedback
    valid_categories: List[str]         # valid labels for Task 1
    remaining_items: int                # items left to process
```

---

## 🏗️ Setup & Usage

### Install
```bash
pip install openenv-core python-dotenv
pip install git+https://huggingface.co/spaces/RAc1928/second-brain-env
```

### Run locally with Docker
```bash
git clone https://huggingface.co/spaces/RAc1928/second-brain-env
cd second-brain-env

docker build -t second-brain-env .
docker run -p 8000:8000 -p 8001:8001 -p 8002:8002 -p 8003:8003 second-brain-env
```

### Connect as a client
```python
import asyncio
from second_brain_env import SecondBrainEnv, SecondBrainAction

async def main():
    async with SecondBrainEnv(base_url="http://localhost:8000") as env:
        # Reset
        result = await env.reset()
        print(result.observation.feedback)

        # Task 1: categorize a note
        result = await env.step(SecondBrainAction(
            action_type="categorize",
            content="work"
        ))
        print(f"Reward: {result.observation.reward}")
        print(f"Score:  {result.observation.score}")

asyncio.run(main())
```

### Run baseline inference
```bash
export HF_TOKEN=hf_your_token_here
export API_BASE_URL=https://router.huggingface.co/v1
export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
export SECOND_BRAIN_URL=http://localhost:8000

python inference.py
```

### Validate submission
```bash
openenv validate
```

---

## 📊 Baseline Scores

Scores produced by the `Qwen/Qwen2.5-72B-Instruct` model via HuggingFace router:

| Task | Difficulty | Baseline Score |
|---|---|---|
| `note_categorization` | 🟢 Easy | 0.70 |
| `memory_retrieval` | 🟡 Medium | 0.52 |
| `knowledge_synthesis` | 🔴 Hard | 0.38 |
| **Average** | | **0.53** |

---

## 🔁 Reward Design

Rewards are **dense** — every step produces a signal:

```
Task 1 (categorization):
  Correct category  → +0.10  (agent gets immediate confirmation)
  Wrong category    → -0.02  (small penalty, not catastrophic)
  Skip              →  0.00  (neutral — no progress)

Task 2 (retrieval):
  Exact match       → +0.20  (top-1 is the correct note)
  Near miss rank 2  → +0.16  (partial credit)
  Near miss rank 3  → +0.12
  Not in top 5      → -0.05  (try a different query)
  3 consecutive bad → -0.10  (penalty for looping)

Task 3 (synthesis):
  Per relevant note found   → +0.05
  Synthesis theme coverage  → up to +0.12
  Synthesis note coverage   → up to +0.11
  Answer length bonus       → up to +0.07
  Multi-theme connection    → +0.05 bonus
  Hallucinated facts        → -0.10 penalty
```

---

## 🐳 Docker

```bash
# Build
docker build -t second-brain-env .

# Run (starts all 3 task servers automatically)
docker run -p 8000:8000 -p 8001:8001 -p 8002:8002 -p 8003:8003 second-brain-env

# Test
curl -X POST http://localhost:8000/reset
curl -X POST http://localhost:8000/step \
  -H "Content-Type: application/json" \
  -d '{"action_type": "categorize", "content": "work"}'
```

---

## 📁 Project Structure

```
second_brain_env/
├── inference.py          ← baseline inference script (root level)
├── openenv.yaml          ← environment manifest
├── pyproject.toml        ← dependencies
├── README.md
├── __init__.py           ← exports Action, Observation, Env
├── models.py             ← Pydantic typed models
├── client.py             ← WebSocket client
└── server/
    ├── app.py            ← FastAPI server
    ├── second_brain_env_environment.py  ← step/reset/state logic
    ├── data.py           ← seed notes and knowledge base
    ├── requirements.txt
    └── Dockerfile
```

---

## 👥 Team

**Team TwinCoders**
- Rachana N 
- Rakshith N

Built for the Meta × PyTorch × HuggingFace OpenEnv Hackathon 2026.