From 3ccf4bc383cfb9e9f95e5e64898eb3e1beba64d3 Mon Sep 17 00:00:00 2001
From: Shivam Sharma <91240327+shivamhwp@users.noreply.github.com>
Date: Thu, 29 Jan 2026 04:26:12 +0530
Subject: [PATCH] Address PR review feedback

- Restore MCP server configurations in .mcp.json with updated paths
  for separate virtual environments (core/.venv and tools/.venv)
- Align Python version: change .python-version from 3.13 to 3.11
  to match pyproject.toml target version
- Remove AGENTS.md as suggested (quickstart is sufficient)
- Document cross-package imports and separate venv architecture
  in ENVIRONMENT_SETUP.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .mcp.json            | 13 ++++++++-
 .python-version      |  2 +-
 AGENTS.md            |  1 -
 ENVIRONMENT_SETUP.md | 64 +++++++++++++++++++++++++++++++++++++++++---
 4 files changed, 73 insertions(+), 7 deletions(-)
 delete mode 100644 AGENTS.md

diff --git a/.mcp.json b/.mcp.json
index 70011302..ace49fd6 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -1,3 +1,14 @@
 {
-  "mcpServers": {}
+  "mcpServers": {
+    "agent-builder": {
+      "command": "core/.venv/bin/python",
+      "args": ["-m", "framework.mcp.agent_builder_server"],
+      "cwd": "."
+    },
+    "tools": {
+      "command": "tools/.venv/bin/python",
+      "args": ["-m", "aden_tools.mcp_server", "--stdio"],
+      "cwd": "."
+    }
+  }
 }
\ No newline at end of file
diff --git a/.python-version b/.python-version
index 24ee5b1b..2c073331 100644
--- a/.python-version
+++ b/.python-version
@@ -1 +1 @@
-3.13
+3.11
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 100644
index 816df426..00000000
--- a/AGENTS.md
+++ /dev/null
@@ -1 +0,0 @@
-1. this project uses uv as the package manager. ty as the type checker and ruff as the linter.
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 14d0c5f0..be093c5f 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -325,14 +325,14 @@ The Hive framework consists of three Python packages:
 hive/
 ├── core/                    # Core framework (runtime, graph executor, LLM providers)
 │   ├── framework/
-│   ├── pyproject.toml
-│   └── requirements.txt
+│   ├── .venv/              # Isolated virtual environment for core
+│   └── pyproject.toml
 │
 ├── tools/                   # Tools and MCP servers
 │   ├── src/
 │   │   └── aden_tools/     # Actual package location
-│   ├── pyproject.toml
-│   └── README.md
+│   ├── .venv/              # Isolated virtual environment for tools
+│   └── pyproject.toml
 │
 └── exports/                 # Agent packages (your agents go here)
     ├── support_ticket_agent/
@@ -341,6 +341,62 @@ hive/
     └── personal_assistant_agent/
 ```
 
+## Separate Virtual Environments
+
+The project uses **separate virtual environments** for `core` and `tools` packages to:
+
+- Isolate dependencies and avoid conflicts
+- Allow independent development and testing of each package
+- Enable MCP servers to run with their specific dependencies
+
+### How It Works
+
+When you run `./quickstart.sh` or `uv sync` in each directory:
+
+1. **core/.venv/** - Contains the `framework` package and its dependencies (anthropic, litellm, mcp, etc.)
+2. **tools/.venv/** - Contains the `aden_tools` package and its dependencies (beautifulsoup4, pandas, etc.)
+
+### Cross-Package Imports
+
+The `core` and `tools` packages are **intentionally independent**:
+
+- **No cross-imports**: `framework` does not import `aden_tools` directly, and vice versa
+- **Communication via MCP**: Tools are exposed to agents through MCP servers, not direct Python imports
+- **Runtime integration**: The agent runner loads tools via the MCP protocol at runtime
+
+If you need to use both packages in a single script (e.g., for testing), you have two options:
+
+```bash
+# Option 1: Install both in a shared environment
+python -m venv .venv
+source .venv/bin/activate
+pip install -e core/ -e tools/
+
+# Option 2: Use PYTHONPATH (for quick testing)
+PYTHONPATH=core:tools/src python your_script.py
+```
+
+### MCP Server Configuration
+
+The `.mcp.json` at project root configures MCP servers to use their respective virtual environments:
+
+```json
+{
+  "mcpServers": {
+    "agent-builder": {
+      "command": "core/.venv/bin/python",
+      "args": ["-m", "framework.mcp.agent_builder_server"]
+    },
+    "tools": {
+      "command": "tools/.venv/bin/python",
+      "args": ["-m", "aden_tools.mcp_server", "--stdio"]
+    }
+  }
+}
+```
+
+This ensures each MCP server runs with its correct dependencies.
+
 ### Why PYTHONPATH is Required
 
 The packages are installed in **editable mode** (`pip install -e`), which means: