base

.gitignore

@@ -0,0 +1,156 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+*.tmp
+*.temp
+
+# Docker (if building locally)
+.dockerignore

README.md

@@ -0,0 +1,228 @@
+# 🧠 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
+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 -f server/Dockerfile .
+docker run -p 8000:8000 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 -f server/Dockerfile .
+
+# Run
+docker run -p 8000:8000 -e TASK_NAME=note_categorization 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 (RAc1928)
+- Rakshith N
+
+Built for the Meta × PyTorch × HuggingFace OpenEnv Hackathon 2026.

__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Second Brain Env Environment."""
+
+from .client import SecondBrainEnv
+from .models import SecondBrainAction, SecondBrainObservation
+
+__all__ = [
+    "SecondBrainAction",
+    "SecondBrainObservation",
+    "SecondBrainEnv",
+]

client.py

@@ -0,0 +1,31 @@
+"""
+Second Brain Environment — WebSocket Client
+Connects to the running server and exposes reset()/step()/state().
+"""
+from openenv.core.env_client import EnvClient
+from models import SecondBrainAction, SecondBrainObservation
+
+
+class SecondBrainEnv(EnvClient):
+    """
+    Client for the Second Brain OpenEnv environment.
+
+    Usage:
+        async with SecondBrainEnv(base_url="http://localhost:8000") as env:
+            result = await env.reset()
+            result = await env.step(SecondBrainAction(
+                action_type="categorize",
+                content="work"
+            ))
+
+    Or from a deployed HF Space:
+        async with SecondBrainEnv(base_url="https://RAc1928-second-brain-env.hf.space") as env:
+            ...
+    """
+
+    action_type      = SecondBrainAction
+    observation_type = SecondBrainObservation
+
+    def __init__(self, base_url: str = "http://localhost:8000", task_name: str = "note_categorization"):
+        super().__init__(base_url=base_url)
+        self._task_name = task_name

models.py

@@ -0,0 +1,144 @@
+"""
+Typed models for the Second Brain OpenEnv environment.
+Defines Action, Observation, and State using proper OpenEnv inheritance.
+"""
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import Field
+ 
+from openenv.core.env_server import Action, Observation
+from openenv.core.env_server.types import State
+ 
+ 
+# ---------------------------------------------------------------------------
+# ActionType Enum — prevents typos like "categorise" instead of "categorize"
+# ---------------------------------------------------------------------------
+ 
+class ActionType(str, Enum):
+    categorize = "categorize"
+    retrieve   = "retrieve"
+    synthesize = "synthesize"
+    tag        = "tag"
+    skip       = "skip"
+ 
+ 
+# ---------------------------------------------------------------------------
+# Action — inherits from OpenEnv Action
+# ---------------------------------------------------------------------------
+ 
+class SecondBrainAction(Action):
+    """
+    A single action the agent can take in the Second Brain environment.
+ 
+    action_type options:
+      - categorize : assign a category to the current note (Task 1)
+      - retrieve   : query the knowledge base with a search string (Task 2 & 3)
+      - synthesize : produce a final synthesized answer (Task 3)
+      - tag        : add tags to a note
+      - skip       : skip the current item (no reward)
+ 
+    Fields:
+      action_type  : validated enum — prevents typos
+      content      : category name / search query / synthesized answer
+      note_id      : optional — which note to act on
+      tags         : optional list of tags
+    """
+    action_type: ActionType = Field(
+        ...,
+        description="One of: categorize | retrieve | synthesize | tag | skip"
+    )
+    content: str = Field(
+        ...,
+        description="Main payload: category name, search query, or synthesized answer"
+    )
+    note_id: Optional[str] = Field(
+        default=None,
+        description="Target note ID for retrieve or tag actions"
+    )
+    tags: Optional[List[str]] = Field(
+        default=None,
+        description="List of tags to apply (used with action_type='tag')"
+    )
+ 
+ 
+# ---------------------------------------------------------------------------
+# Observation — inherits from OpenEnv Observation
+# ---------------------------------------------------------------------------
+ 
+class SecondBrainObservation(Observation):
+    """
+    What the agent observes after each step.
+ 
+    Fields:
+      current_note      : the note currently being processed (Task 1)
+      query             : the retrieval question (Task 2 & 3)
+      retrieved_notes   : notes returned by a retrieve action
+      knowledge_base_size : how many notes are in the KB
+      step_count        : current step number
+      task_name         : which task is active
+      reward            : reward from the last action
+      done              : whether the episode is finished
+      score             : running cumulative score (0.0–1.0)
+      feedback          : human-readable feedback on last action
+      valid_categories  : categories the agent may use (Task 1)
+      remaining_items   : how many items still need processing
+    """
+    current_note: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="The note currently presented to the agent"
+    )
+    query: Optional[str] = Field(
+        default=None,
+        description="The retrieval question the agent must answer"
+    )
+    retrieved_notes: Optional[List[Dict[str, Any]]] = Field(
+        default=None,
+        description="Notes returned after a retrieve action"
+    )
+    knowledge_base_size: int = Field(
+        default=0,
+        description="Total notes in the knowledge base"
+    )
+    step_count: int = Field(default=0)
+    task_name: str = Field(default="")
+    reward: float = Field(default=0.0)
+    done: bool = Field(default=False)
+    score: float = Field(default=0.0, description="Running score in [0, 1]")
+    feedback: str = Field(default="", description="Feedback on the last action")
+    valid_categories: List[str] = Field(
+        default_factory=lambda: ["work", "personal", "reference", "action_item"],
+        description="Valid category labels for Task 1"
+    )
+    remaining_items: int = Field(
+        default=0,
+        description="Number of items still to be processed this episode"
+    )
+ 
+ 
+# ---------------------------------------------------------------------------
+# State — extends OpenEnv State with environment-specific fields
+# ---------------------------------------------------------------------------
+ 
+class SecondBrainState(State):
+    """
+    Full internal state of the Second Brain environment.
+    Used by state() endpoint and for debugging/graders.
+ 
+    Fields:
+      task_name    : which task is currently running
+      step_count   : how many steps have been taken
+      score        : current normalized score in [0.0, 1.0]
+      correct_count       : Task 1 — correct categorizations so far
+      retrieval_scores    : Task 2 — list of per-question retrieval scores
+      synthesis_scores    : Task 3 — list of per-question synthesis scores
+      collected_note_ids  : Task 3 — notes collected before synthesizing
+      done         : whether the episode has ended
+    """
+    task_name: str = Field(default="")
+    step_count: int = Field(default=0)
+    score: float = Field(default=0.0)
+    correct_count: int = Field(default=0)
+    retrieval_scores: List[float] = Field(default_factory=list)
+    synthesis_scores: List[float] = Field(default_factory=list)
+    collected_note_ids: List[str] = Field(default_factory=list)
+    done: bool = Field(default=False)

openenv.yaml

@@ -0,0 +1,99 @@
+name: second_brain_env
+version: "1.0.0"
+description: >
+  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. Three tasks of increasing difficulty:
+  note categorization (easy), memory retrieval (medium), and knowledge
+  synthesis (hard).
+author: RAc1928
+tags:
+  - openenv
+  - knowledge-management
+  - information-retrieval
+  - real-world
+  - nlp
+
+tasks:
+  - name: note_categorization
+    difficulty: easy
+    description: Categorize 10 raw notes into correct categories (work/personal/reference/action_item)
+    max_steps: 12
+    reward_range: [-0.02, 0.10]
+    success_threshold: 0.5
+
+  - name: memory_retrieval
+    difficulty: medium
+    description: Retrieve the most relevant note from a 30-note knowledge base for each of 5 questions
+    max_steps: 15
+    reward_range: [-0.10, 0.20]
+    success_threshold: 0.5
+
+  - name: knowledge_synthesis
+    difficulty: hard
+    description: Collect and synthesize insights from a 50-note knowledge base to answer complex multi-theme questions
+    max_steps: 20
+    reward_range: [-0.10, 0.35]
+    success_threshold: 0.5
+
+action_space:
+  type: SecondBrainAction
+  fields:
+    action_type:
+      type: string
+      enum: [categorize, retrieve, synthesize, tag, skip]
+    content:
+      type: string
+      description: Category name / search query / synthesized answer
+    note_id:
+      type: string
+      optional: true
+    tags:
+      type: array
+      items: string
+      optional: true
+
+observation_space:
+  type: SecondBrainObservation
+  fields:
+    current_note:
+      type: object
+      optional: true
+    query:
+      type: string
+      optional: true
+    retrieved_notes:
+      type: array
+      optional: true
+    knowledge_base_size:
+      type: integer
+    step_count:
+      type: integer
+    task_name:
+      type: string
+    reward:
+      type: float
+    done:
+      type: boolean
+    score:
+      type: float
+      description: Running normalized score in [0.0, 1.0]
+    feedback:
+      type: string
+    valid_categories:
+      type: array
+      items: string
+    remaining_items:
+      type: integer
+
+environment:
+  type: http
+  framework: fastapi
+  dockerfile: server/Dockerfile
+  port: 8000
+  endpoints:
+    reset: POST /reset
+    step:  POST /step
+    state: GET  /state
+    tasks: GET  /tasks
+    health: GET /health

pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-second_brain_env"
+version = "0.1.0"
+description = "Second Brain Env environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m second_brain_env.server.app
+server = "second_brain_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["second_brain_env", "second_brain_env.server"]
+package-dir = { "second_brain_env" = ".", "second_brain_env.server" = "server" }

server/Dockerfile

@@ -0,0 +1,80 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=second_brain_env
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Second Brain Env environment server components."""
+
+from .second_brain_env_environment import SecondBrainEnvironment
+
+__all__ = ["SecondBrainEnvironment"]

server/app.py

@@ -0,0 +1,84 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Second Brain Env Environment.
+
+This module creates an HTTP server that exposes the SecondBrainEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with '\n    uv sync\n'"
+    ) from e
+
+try:
+    from ..models import SecondBrainAction, SecondBrainObservation
+    from .second_brain_env_environment import SecondBrainEnvironment
+except ModuleNotFoundError:
+    from models import SecondBrainAction, SecondBrainObservation
+    from server.second_brain_env_environment import SecondBrainEnvironment
+
+
+# Create the app with web interface and README integration
+app = create_app(
+    SecondBrainEnvironment,
+    SecondBrainAction,
+    SecondBrainObservation,
+    env_name="second_brain_env",
+    max_concurrent_envs=1,  # increase this number to allow more concurrent WebSocket sessions
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    """
+    Entry point for direct execution via uv run or python -m.
+
+    This function enables running the server without Docker:
+        uv run --project . server
+        uv run --project . server --port 8001
+        python -m second_brain_env.server.app
+
+    Args:
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port number to listen on (default: 8000)
+
+    For production deployments, consider using uvicorn directly with
+    multiple workers:
+        uvicorn second_brain_env.server.app:app --workers 4
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

server/data.py

@@ -0,0 +1,209 @@
+"""
+Seed data for the Second Brain environment.
+Fixed seed ensures reproducible scores across all runs.
+"""
+from typing import Any, Dict, List
+
+# ---------------------------------------------------------------------------
+# Task 1 — 10 notes to categorize
+# ---------------------------------------------------------------------------
+TASK1_NOTES: List[Dict[str, Any]] = [
+    {
+        "id": "n001",
+        "text": "Follow up with Priya about the Q3 budget report by Friday.",
+        "correct_category": "action_item",
+    },
+    {
+        "id": "n002",
+        "text": "Interesting article: how sleep affects memory consolidation. Save for later.",
+        "correct_category": "reference",
+    },
+    {
+        "id": "n003",
+        "text": "Team standup notes: backend blocked on auth service, frontend ready to demo.",
+        "correct_category": "work",
+    },
+    {
+        "id": "n004",
+        "text": "Mom's birthday is on the 18th. Order cake from the bakery near home.",
+        "correct_category": "personal",
+    },
+    {
+        "id": "n005",
+        "text": "Research paper on vector databases — useful for the recommendation engine project.",
+        "correct_category": "reference",
+    },
+    {
+        "id": "n006",
+        "text": "Book dentist appointment before end of month.",
+        "correct_category": "action_item",
+    },
+    {
+        "id": "n007",
+        "text": "1:1 with manager: discussed promotion timeline, need to finish tech spec first.",
+        "correct_category": "work",
+    },
+    {
+        "id": "n008",
+        "text": "Watched a great documentary about the ocean. Want to go snorkeling someday.",
+        "correct_category": "personal",
+    },
+    {
+        "id": "n009",
+        "text": "Python typing cheatsheet — quick reference for generics and protocols.",
+        "correct_category": "reference",
+    },
+    {
+        "id": "n010",
+        "text": "Send invoice #1042 to client by Thursday.",
+        "correct_category": "action_item",
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Task 2 — 30-note knowledge base + 5 retrieval questions
+# ---------------------------------------------------------------------------
+TASK2_KNOWLEDGE_BASE: List[Dict[str, Any]] = [
+    {"id": "k001", "text": "Meeting with John on March 5: project deadline pushed to April 15 due to design review.", "topic": "work"},
+    {"id": "k002", "text": "Gym routine: Mon/Wed/Fri — upper body. Tue/Thu — cardio. Rest on weekends.", "topic": "personal"},
+    {"id": "k003", "text": "Book recommendation from Ananya: 'Deep Work' by Cal Newport.", "topic": "reference"},
+    {"id": "k004", "text": "API rate limit for the weather service is 1000 calls/day on free tier.", "topic": "work"},
+    {"id": "k005", "text": "Grocery list: oats, almond milk, spinach, Greek yogurt, eggs.", "topic": "personal"},
+    {"id": "k006", "text": "React useEffect cleanup: return a function to cancel subscriptions and avoid memory leaks.", "topic": "reference"},
+    {"id": "k007", "text": "Call with Priya: she needs the analytics dashboard by end of sprint (March 20).", "topic": "work"},
+    {"id": "k008", "text": "Interesting talk by Andrew Ng on data-centric AI — focus on data quality over model tuning.", "topic": "reference"},
+    {"id": "k009", "text": "Visa appointment booked for June 10 at 9 AM. Bring all original documents.", "topic": "personal"},
+    {"id": "k010", "text": "Tech spec for recommendation engine: use collaborative filtering + content-based hybrid.", "topic": "work"},
+    {"id": "k011", "text": "Password manager: use 1Password for all work accounts. Enable 2FA everywhere.", "topic": "reference"},
+    {"id": "k012", "text": "Flight to Bangalore: April 25, 6:15 AM. Check-in online 24 hours before.", "topic": "personal"},
+    {"id": "k013", "text": "Sprint retrospective: team agreed to reduce WIP limit to 3 tasks per person.", "topic": "work"},
+    {"id": "k014", "text": "How to center a div in CSS: use flexbox with justify-content and align-items set to center.", "topic": "reference"},
+    {"id": "k015", "text": "Dad's medical checkup results came back normal. Next appointment in 6 months.", "topic": "personal"},
+    {"id": "k016", "text": "Vendor contract renewal due on May 1. Legal team needs 2 weeks notice.", "topic": "work"},
+    {"id": "k017", "text": "Python tip: use dataclasses for simple data containers, Pydantic when you need validation.", "topic": "reference"},
+    {"id": "k018", "text": "Movie night idea: Dune Part 2, Everything Everywhere, Past Lives.", "topic": "personal"},
+    {"id": "k019", "text": "Architecture decision: move from monolith to microservices in Q3. Start with auth service.", "topic": "work"},
+    {"id": "k020", "text": "Git workflow: feature branches off main, squash commits before merging, tag releases.", "topic": "reference"},
+    {"id": "k021", "text": "Meditation app: Headspace — doing 10 min daily, helps with focus at work.", "topic": "personal"},
+    {"id": "k022", "text": "Budget for Q2: engineering headcount approved for 2 new hires.", "topic": "work"},
+    {"id": "k023", "text": "Docker tip: use multi-stage builds to reduce final image size significantly.", "topic": "reference"},
+    {"id": "k024", "text": "Weekend plan: visit the botanical garden on Saturday, brunch with friends Sunday.", "topic": "personal"},
+    {"id": "k025", "text": "OKR for Q2: increase API response time by 30%, reduce error rate below 0.1%.", "topic": "work"},
+    {"id": "k026", "text": "Learning resource: fast.ai course for practical deep learning — free and hands-on.", "topic": "reference"},
+    {"id": "k027", "text": "Apartment lease renewal in August. Start looking at options in June.", "topic": "personal"},
+    {"id": "k028", "text": "Code review checklist: check for error handling, test coverage, naming consistency.", "topic": "work"},
+    {"id": "k029", "text": "Pomodoro technique: 25 min focus + 5 min break. After 4 rounds take a longer break.", "topic": "reference"},
+    {"id": "k030", "text": "Sister's wedding anniversary gift: book a dinner reservation at that Italian restaurant.", "topic": "personal"},
+]
+
+TASK2_QUESTIONS: List[Dict[str, Any]] = [
+    {
+        "id": "q001",
+        "question": "What is the deadline for the project that John mentioned?",
+        "correct_note_id": "k001",
+        "keywords": ["john", "deadline", "april", "project"],
+    },
+    {
+        "id": "q002",
+        "question": "What is the API rate limit for the weather service?",
+        "correct_note_id": "k004",
+        "keywords": ["api", "rate limit", "weather", "calls"],
+    },
+    {
+        "id": "q003",
+        "question": "When is the visa appointment and what should I bring?",
+        "correct_note_id": "k009",
+        "keywords": ["visa", "appointment", "documents", "june"],
+    },
+    {
+        "id": "q004",
+        "question": "What architecture approach was decided for Q3?",
+        "correct_note_id": "k019",
+        "keywords": ["architecture", "microservices", "monolith", "auth"],
+    },
+    {
+        "id": "q005",
+        "question": "What is the Python tip about when to use Pydantic vs dataclasses?",
+        "correct_note_id": "k017",
+        "keywords": ["python", "pydantic", "dataclass", "validation"],
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Task 3 — 50-note knowledge base + 3 synthesis questions
+# ---------------------------------------------------------------------------
+# Extends Task 2 KB with 20 more notes
+TASK3_EXTRA_NOTES: List[Dict[str, Any]] = [
+    {"id": "k031", "text": "Feeling overwhelmed with workload this week. Too many meetings, no deep work time.", "topic": "work_stress"},
+    {"id": "k032", "text": "Skipped gym 3 days this week due to late meetings. Energy levels low.", "topic": "health"},
+    {"id": "k033", "text": "Had a great 1:1 with mentor: she suggested blocking 2 hours daily for focused coding.", "topic": "work"},
+    {"id": "k034", "text": "Headache for 2 days. Might be from screen time. Need to take more breaks.", "topic": "health"},
+    {"id": "k035", "text": "Read article: chronic stress reduces productivity by up to 40% over time.", "topic": "reference"},
+    {"id": "k036", "text": "Sprint planning took 3 hours — too long. Propose async planning next time.", "topic": "work_stress"},
+    {"id": "k037", "text": "Back pain from sitting too long. Started doing 5 min stretches every hour.", "topic": "health"},
+    {"id": "k038", "text": "Team morale low after missed deadline. Need to celebrate small wins more.", "topic": "work_stress"},
+    {"id": "k039", "text": "Sleep only 5 hours last 3 nights. Affecting concentration during code reviews.", "topic": "health"},
+    {"id": "k040", "text": "Cancelled weekend plans because of urgent production bug fix. Feeling burnt out.", "topic": "work_stress"},
+    {"id": "k041", "text": "Doctor visit: advised 7-8 hours sleep, regular exercise, reduce caffeine.", "topic": "health"},
+    {"id": "k042", "text": "Tried async standup instead of meeting — saved 45 min and felt less rushed.", "topic": "work"},
+    {"id": "k043", "text": "Coffee intake: 4 cups per day this week. Feel jittery and anxious.", "topic": "health"},
+    {"id": "k044", "text": "Project scope keeps expanding — need to push back on new feature requests.", "topic": "work_stress"},
+    {"id": "k045", "text": "Went for a 30 min walk during lunch — felt much more focused in the afternoon.", "topic": "health"},
+    {"id": "k046", "text": "Boundary setting: stopped checking Slack after 8 PM. Sleep improved immediately.", "topic": "work_stress"},
+    {"id": "k047", "text": "Research: exercise improves cognitive function and reduces stress hormones.", "topic": "reference"},
+    {"id": "k048", "text": "Team agreed: no meetings on Fridays. Using it for deep work and documentation.", "topic": "work"},
+    {"id": "k049", "text": "Mood tracker: consistently lower energy on days with 4+ meetings.", "topic": "health"},
+    {"id": "k050", "text": "Note to self: when stressed, the first thing I skip is exercise. That makes it worse.", "topic": "health"},
+]
+
+TASK3_KNOWLEDGE_BASE = TASK2_KNOWLEDGE_BASE + TASK3_EXTRA_NOTES
+
+TASK3_QUESTIONS: List[Dict[str, Any]] = [
+    {
+        "id": "sq001",
+        "question": "What patterns connect my work stress notes to my health notes? What should I do?",
+        "relevant_note_ids": ["k031", "k032", "k034", "k036", "k037", "k039", "k040", "k043", "k046", "k049", "k050"],
+        "key_themes": ["stress", "health", "exercise", "sleep", "meetings"],
+        "expected_insight": "High meeting load → skipped exercise → poor sleep → low energy → more stress. Breaking the cycle requires protecting exercise time and setting meeting boundaries.",
+    },
+    {
+        "id": "sq002",
+        "question": "What technical decisions have been made for Q2/Q3 and are they consistent?",
+        "relevant_note_ids": ["k010", "k013", "k019", "k022", "k025", "k028", "k042", "k048"],
+        "key_themes": ["architecture", "microservices", "okr", "async", "meetings"],
+        "expected_insight": "Q3 moves to microservices starting with auth, Q2 focuses on performance OKRs. Async work patterns are being adopted (async standup, no-meeting Fridays). Consistent theme: reducing synchronous overhead.",
+    },
+    {
+        "id": "sq003",
+        "question": "What lifestyle changes have I tried and what actually worked?",
+        "relevant_note_ids": ["k021", "k037", "k041", "k042", "k045", "k046", "k048", "k050"],
+        "key_themes": ["meditation", "exercise", "boundaries", "sleep", "productivity"],
+        "expected_insight": "Boundary setting (no Slack after 8pm) and exercise (lunch walks) had immediate positive effects. Meditation helps focus. The challenge is maintaining these when work stress peaks.",
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Category definitions
+# ---------------------------------------------------------------------------
+VALID_CATEGORIES = ["work", "personal", "reference", "action_item"]
+
+# ---------------------------------------------------------------------------
+# Scoring helpers
+# ---------------------------------------------------------------------------
+def keyword_overlap_score(query: str, note_text: str) -> float:
+    """
+    Simple keyword overlap score between a query and a note.
+    Returns a float in [0, 1].
+    """
+    query_words = set(query.lower().split())
+    note_words = set(note_text.lower().split())
+    # Remove common stop words
+    stop_words = {"the", "a", "an", "is", "in", "on", "at", "to", "for",
+                  "of", "and", "or", "but", "with", "my", "i", "what",
+                  "how", "when", "where", "which", "that", "this", "it"}
+    query_words -= stop_words
+    note_words -= stop_words
+    if not query_words:
+        return 0.0
+    overlap = query_words & note_words
+    return len(overlap) / len(query_words)

server/requirements.txt

@@ -0,0 +1,8 @@
+openenv-core>=0.1.0
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+pydantic>=2.0.0
+websockets>=12.0
+ 
+
+

server/second_brain_env_environment.py

@@ -0,0 +1,104 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Second Brain Env Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import SecondBrainAction, SecondBrainObservation
+except ImportError:
+    from models import SecondBrainAction, SecondBrainObservation
+
+
+class SecondBrainEnvironment(Environment):
+    """
+    A simple echo environment that echoes back messages.
+
+    This environment is designed for testing the HTTP server infrastructure.
+    It maintains minimal state and simply echoes back whatever message it receives.
+
+    Example:
+        >>> env = SecondBrainEnvironment()
+        >>> obs = env.reset()
+        >>> print(obs.echoed_message)  # "Second Brain Env environment ready!"
+        >>>
+        >>> obs = env.step(SecondBrainAction(message="Hello"))
+        >>> print(obs.echoed_message)  # "Hello"
+        >>> print(obs.message_length)  # 5
+    """
+
+    # Enable concurrent WebSocket sessions.
+    # Set to True if your environment isolates state between instances.
+    # When True, multiple WebSocket clients can connect simultaneously, each
+    # getting their own environment instance (when using factory mode in app.py).
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        """Initialize the second_brain_env environment."""
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count = 0
+
+    def reset(self) -> SecondBrainObservation:
+        """
+        Reset the environment.
+
+        Returns:
+            SecondBrainObservation with a ready message
+        """
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._reset_count += 1
+
+        return SecondBrainObservation(
+            echoed_message="Second Brain Env environment ready!",
+            message_length=0,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: SecondBrainAction) -> SecondBrainObservation:  # type: ignore[override]
+        """
+        Execute a step in the environment by echoing the message.
+
+        Args:
+            action: SecondBrainAction containing the message to echo
+
+        Returns:
+            SecondBrainObservation with the echoed message and its length
+        """
+        self._state.step_count += 1
+
+        message = action.message
+        length = len(message)
+
+        # Simple reward: longer messages get higher rewards
+        reward = length * 0.1
+
+        return SecondBrainObservation(
+            echoed_message=message,
+            message_length=length,
+            done=False,
+            reward=reward,
+            metadata={"original_message": message, "step": self._state.step_count},
+        )
+
+    @property
+    def state(self) -> State:
+        """
+        Get the current environment state.
+
+        Returns:
+            Current State with episode_id and step_count
+        """
+        return self._state