Spaces:

RAc1928
/

second-brain-env

Running

App Files Files Community

second-brain-env / README.md

Rakshithn123

tryoing out inference

b4b9b2e 7 months ago

preview code

Raw History Blame Contribute Delete

7.42 kB

---
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.

	---
	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.