# AIBE Server - AI Browser Extension Interface
**AI Browser Extension Interface Server** enables AI systems to observe and control web browsers through a standardized HTTP API. The system synchronizes your physical browser with a virtual browser, allowing AI to see exactly what you see and act exactly like a human user.
**Core Philosophy: "What the user can see and what they can do"** - The system captures only what's visible and interactive to humans, creating a natural interface for AI systems to understand and navigate web applications without complex DOM parsing or brittle selectors.
**Why use AIBE?** Instead of teaching AI systems to reverse-engineer web pages, AIBE lets them work with the same interface humans use. This makes AI browser automation more reliable, intuitive, and adaptable to any web application.
This is the server component that works with the AIBE Chrome extension to implement the Generic User Framework for AI-browser interaction.
*Learn more about the research and development behind this project at [AI & Me](https://paulhanchett.com).*
## Installation
### PyPI Installation (Recommended)
For most users, install from PyPI with a virtual environment:
```bash
# Create virtual environment (recommended)
python -m venv .venv
# Activate virtual environment
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate
# Install from PyPI
pip install aibe-server
```
**Why use a virtual environment?** Virtual environments isolate your project dependencies, preventing conflicts with other Python packages on your system. The `.venv` directory name is a Python standard that most editors and tools recognize automatically.
### Development Installation
For developers who want to modify the source code:
> **Note:** The source repository is private. For collaborator access, please contact paul@paulhanchett.com with details about your intended contribution.
```bash
# Clone the repository (requires access)
git clone <repository-url>
cd ai-browser-extension/server
# Create virtual environment
python -m venv .venv
# Activate virtual environment
source .venv/bin/activate # Windows: .venv\Scripts\activate
# Install dependencies and package in editable mode
pip install -e .
```
This installs the package in "editable mode" - changes to the source code take effect immediately without reinstalling.
## Quick Start
### 1. Start the Server
**If you installed from PyPI:**
```bash
# Make sure your virtual environment is activated
# Then start the server:
aibe-server start
# Check server status:
aibe-server status
# Stop server when done:
aibe-server stop
```
**If you're using the development installation:**
The server includes a unified management system with additional controls:
*Windows:*
```cmd
.\server.bat start # Start server
.\server.bat stop # Stop server
.\server.bat restart # Restart server
.\server.bat status # Show server status
```
*Linux/WSL/macOS:*
```bash
./server start # Start server
./server stop # Stop server
./server restart # Restart server
./server status # Show server status
```
**Management features (development install only):**
- Auto-detects and activates virtual environment
- Cross-platform process management
- Proper detached server processes
- Rich status reporting with platform detection
- Handles cross-space detection (Windows vs WSL)
The server will start on `http://localhost:3001`
## Command-Line Interface
The AIBE server provides a complete CLI for server management:
### Available Commands
```bash
aibe-server start # Start server in background
aibe-server stop # Stop the running server
aibe-server restart # Restart the server
aibe-server status # Show server status and information
aibe-server help # Show this help message
```
### Command Details
**Start Server:**
```bash
aibe-server start
```
Starts the server in background mode on port 3001. Shows PID, installation path, and connection URL when successful.
**Check Status:**
```bash
aibe-server status
```
Displays comprehensive server information including:
- Server running status (running/not running)
- Installation path and PID
- Server uptime and platform
- Active sessions and event counts
- Available commands for current platform
**Stop Server:**
```bash
aibe-server stop
```
Gracefully shuts down the running server. Works across platforms (Windows/Linux/WSL) with proper process management.
**Restart Server:**
```bash
aibe-server restart
```
Stops the current server instance and starts a new one. Useful during development or after configuration changes.
**Get Help:**
```bash
aibe-server help
# or
aibe-server --help
# or
aibe-server -h
```
Shows complete command reference with examples and usage information.
### 2. Install Chrome Extension
#### Option A: Download from Server (Recommended for PyPI installs)
1. Check server status to see installation location:
```bash
aibe-server status
```
2. Visit `http://localhost:3001/extension/install` in your browser
3. Follow the installation guide to download all extension files
4. Load the extension in Chrome Developer Mode
#### Option B: Use Local Files (If you have the full repository)
1. Open Chrome and go to `chrome://extensions/`
2. Enable "Developer mode" (toggle in top right)
3. Click "Load unpacked"
4. Select the `server/extension` directory (containing `manifest.json`)
5. The extension should appear in your extensions list
The extension will automatically connect to the server on `localhost:3001`.
### 3. Verify Connection
Visit `http://localhost:3001/status` to see server status and connected sessions.
### 4. Run Tests (Optional)
The server includes comprehensive test suites to validate functionality:
**Web-based test runner:**
- Visit `http://localhost:3001/test-runner` in your browser
- Runs 48 automated tests covering all major functionality
- Interactive interface with real-time results
**Command-line test runner:**
```bash
# From server directory
node tests/console-runner.js
```
Both test runners validate:
- Event capture and processing
- Session management
- Form controls (inputs, dropdowns, checkboxes, radio buttons)
- Dynamic content handling
- Browser interaction capabilities
## Key Features
- **Observer Channel**: Captures user interactions and screen states
- **Actor Channel**: Foundation for AI systems to interact with the browser
- **Session Management**: Isolates browser tabs with unique session IDs
- **Event Processing**: Real-time event capture and queuing
- **Testing Framework**: Built-in test suites for validation
- **Virtual Environment**: Isolated Python installation to avoid conflicts
## API Endpoints
### Status & Health
- `GET /status` - Server status and session information
- `GET /health` - Simple health check
### Event Capture (Observer)
- `POST /events` - Submit browser events
- `GET /events/{session_id}` - Get events for session
- `GET /events/{session_id}/latest` - Get latest events
### Browser Control (Actor)
- `POST /commands/{session_id}` - Send commands to browser
- `GET /commands/{session_id}` - Get pending commands
- `DELETE /commands/{session_id}/{command_id}` - Remove command
### Session Management
- `GET /sessions` - List all sessions
- `POST /sessions` - Create new session
- `GET /sessions/{session_id}` - Get session details
## Configuration
The server can be configured via environment variables:
```bash
AIBE_PORT=3001 # Server port (default: 3001)
AIBE_DEBUG=true # Enable debug logging
AIBE_LOG_LEVEL=info # Logging level
```
## Architecture
AIBE implements a dual-channel architecture:
1. **Observer Channel**: Browser → Server (events, screen state)
2. **Actor Channel**: Server → Browser (commands, actions)
This enables AI systems to both learn from human interactions and take autonomous actions.
## Generic User Framework
AIBE is designed to support the Generic User Framework (GUA), where:
- **Task Domain AI**: Focuses on business logic and goals
- **Browser Interaction AI**: Handles web navigation mechanics
- **AIBE Server**: Provides the technical bridge between AI and browser
## Testing
The server includes comprehensive test suites:
```bash
# Run validation tests
python validate_core.py
# Start test runner web interface
# Visit http://localhost:3001/test-runner
```
## Development
### Project Structure
```
server/
├── aibe_server/ # Main package
│ ├── main.py # FastAPI application
│ ├── session_manager.py
│ ├── models/ # Pydantic models
│ ├── middleware/ # Custom middleware
│ ├── utils/ # Utilities
│ ├── static/ # Web assets
│ └── templates/ # HTML templates
├── server.py # Entry point
├── install.py # Automatic installer
├── pyproject.toml # Package configuration
└── requirements.txt # Dependencies
```
### Running from Source
```bash
# Using the installer (recommended)
python install.py
# Or manually
pip install -r requirements.txt
python server.py
```
## Virtual Environment Benefits
The automatic installation creates an isolated Python environment that:
- Prevents conflicts with system Python packages
- Works on systems where users can't install global packages
- Ensures consistent dependency versions
- Makes uninstallation clean (just delete `~/.aibe-server/`)
## Research Context
AIBE is part of ongoing research into:
- **Persistent Cognitive Architectures** for AI systems
- **Human-AI Collaboration** patterns and methodologies
- **Generic User Framework** for universal web interaction
- **Memory Agent** concepts for continuous learning
## License
MIT License - See LICENSE file for details.
## Support
- **Documentation**: https://paulhanchett.com/aibe/manual
- **Research Papers**: https://paulhanchett.com/research
## Citation
If you use AIBE in research, please cite:
```bibtex
@software{hanchett2025aibe,
title={AI Browser Extension Interface: Enabling AI Systems to Navigate Web Interfaces},
author={Hanchett, Paul},
year={2025},
url={https://paulhanchett.com/aibe}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "aibe-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, browser, automation, generic-user-framework, web-interface",
"author": null,
"author_email": "Paul Hanchett <paul@paulhanchett.com>",
"download_url": null,
"platform": null,
"description": "# AIBE Server - AI Browser Extension Interface\r\n\r\n**AI Browser Extension Interface Server** enables AI systems to observe and control web browsers through a standardized HTTP API. The system synchronizes your physical browser with a virtual browser, allowing AI to see exactly what you see and act exactly like a human user.\r\n\r\n**Core Philosophy: \"What the user can see and what they can do\"** - The system captures only what's visible and interactive to humans, creating a natural interface for AI systems to understand and navigate web applications without complex DOM parsing or brittle selectors.\r\n\r\n**Why use AIBE?** Instead of teaching AI systems to reverse-engineer web pages, AIBE lets them work with the same interface humans use. This makes AI browser automation more reliable, intuitive, and adaptable to any web application.\r\n\r\nThis is the server component that works with the AIBE Chrome extension to implement the Generic User Framework for AI-browser interaction.\r\n\r\n*Learn more about the research and development behind this project at [AI & Me](https://paulhanchett.com).*\r\n\r\n## Installation\r\n\r\n### PyPI Installation (Recommended)\r\n\r\nFor most users, install from PyPI with a virtual environment:\r\n\r\n```bash\r\n# Create virtual environment (recommended)\r\npython -m venv .venv\r\n\r\n# Activate virtual environment\r\n# Linux/macOS:\r\nsource .venv/bin/activate\r\n# Windows:\r\n.venv\\Scripts\\activate\r\n\r\n# Install from PyPI\r\npip install aibe-server\r\n```\r\n\r\n**Why use a virtual environment?** Virtual environments isolate your project dependencies, preventing conflicts with other Python packages on your system. The `.venv` directory name is a Python standard that most editors and tools recognize automatically.\r\n\r\n### Development Installation\r\n\r\nFor developers who want to modify the source code:\r\n\r\n> **Note:** The source repository is private. For collaborator access, please contact paul@paulhanchett.com with details about your intended contribution.\r\n\r\n```bash\r\n# Clone the repository (requires access)\r\ngit clone <repository-url>\r\ncd ai-browser-extension/server\r\n\r\n# Create virtual environment\r\npython -m venv .venv\r\n\r\n# Activate virtual environment\r\nsource .venv/bin/activate # Windows: .venv\\Scripts\\activate\r\n\r\n# Install dependencies and package in editable mode\r\npip install -e .\r\n```\r\n\r\nThis installs the package in \"editable mode\" - changes to the source code take effect immediately without reinstalling.\r\n\r\n## Quick Start\r\n\r\n### 1. Start the Server\r\n\r\n**If you installed from PyPI:**\r\n```bash\r\n# Make sure your virtual environment is activated\r\n# Then start the server:\r\naibe-server start\r\n\r\n# Check server status:\r\naibe-server status\r\n\r\n# Stop server when done:\r\naibe-server stop\r\n```\r\n\r\n**If you're using the development installation:**\r\nThe server includes a unified management system with additional controls:\r\n\r\n*Windows:*\r\n```cmd\r\n.\\server.bat start # Start server\r\n.\\server.bat stop # Stop server \r\n.\\server.bat restart # Restart server\r\n.\\server.bat status # Show server status\r\n```\r\n\r\n*Linux/WSL/macOS:*\r\n```bash\r\n./server start # Start server\r\n./server stop # Stop server\r\n./server restart # Restart server \r\n./server status # Show server status\r\n```\r\n\r\n**Management features (development install only):**\r\n- Auto-detects and activates virtual environment\r\n- Cross-platform process management\r\n- Proper detached server processes\r\n- Rich status reporting with platform detection\r\n- Handles cross-space detection (Windows vs WSL)\r\n\r\nThe server will start on `http://localhost:3001`\r\n\r\n## Command-Line Interface\r\n\r\nThe AIBE server provides a complete CLI for server management:\r\n\r\n### Available Commands\r\n\r\n```bash\r\naibe-server start # Start server in background\r\naibe-server stop # Stop the running server \r\naibe-server restart # Restart the server\r\naibe-server status # Show server status and information\r\naibe-server help # Show this help message\r\n```\r\n\r\n### Command Details\r\n\r\n**Start Server:**\r\n```bash\r\naibe-server start\r\n```\r\nStarts the server in background mode on port 3001. Shows PID, installation path, and connection URL when successful.\r\n\r\n**Check Status:**\r\n```bash\r\naibe-server status \r\n```\r\nDisplays comprehensive server information including:\r\n- Server running status (running/not running)\r\n- Installation path and PID\r\n- Server uptime and platform\r\n- Active sessions and event counts\r\n- Available commands for current platform\r\n\r\n**Stop Server:**\r\n```bash\r\naibe-server stop\r\n```\r\nGracefully shuts down the running server. Works across platforms (Windows/Linux/WSL) with proper process management.\r\n\r\n**Restart Server:**\r\n```bash\r\naibe-server restart\r\n```\r\nStops the current server instance and starts a new one. Useful during development or after configuration changes.\r\n\r\n**Get Help:**\r\n```bash\r\naibe-server help\r\n# or\r\naibe-server --help\r\n# or \r\naibe-server -h\r\n```\r\nShows complete command reference with examples and usage information.\r\n\r\n### 2. Install Chrome Extension\r\n\r\n#### Option A: Download from Server (Recommended for PyPI installs)\r\n1. Check server status to see installation location:\r\n ```bash\r\n aibe-server status\r\n ```\r\n2. Visit `http://localhost:3001/extension/install` in your browser\r\n3. Follow the installation guide to download all extension files\r\n4. Load the extension in Chrome Developer Mode\r\n\r\n#### Option B: Use Local Files (If you have the full repository)\r\n1. Open Chrome and go to `chrome://extensions/`\r\n2. Enable \"Developer mode\" (toggle in top right)\r\n3. Click \"Load unpacked\"\r\n4. Select the `server/extension` directory (containing `manifest.json`)\r\n5. The extension should appear in your extensions list\r\n\r\nThe extension will automatically connect to the server on `localhost:3001`.\r\n\r\n### 3. Verify Connection\r\n\r\nVisit `http://localhost:3001/status` to see server status and connected sessions.\r\n\r\n### 4. Run Tests (Optional)\r\n\r\nThe server includes comprehensive test suites to validate functionality:\r\n\r\n**Web-based test runner:**\r\n- Visit `http://localhost:3001/test-runner` in your browser\r\n- Runs 48 automated tests covering all major functionality\r\n- Interactive interface with real-time results\r\n\r\n**Command-line test runner:**\r\n```bash\r\n# From server directory\r\nnode tests/console-runner.js\r\n```\r\n\r\nBoth test runners validate:\r\n- Event capture and processing\r\n- Session management\r\n- Form controls (inputs, dropdowns, checkboxes, radio buttons)\r\n- Dynamic content handling\r\n- Browser interaction capabilities\r\n\r\n## Key Features\r\n\r\n- **Observer Channel**: Captures user interactions and screen states\r\n- **Actor Channel**: Foundation for AI systems to interact with the browser\r\n- **Session Management**: Isolates browser tabs with unique session IDs\r\n- **Event Processing**: Real-time event capture and queuing \r\n- **Testing Framework**: Built-in test suites for validation\r\n- **Virtual Environment**: Isolated Python installation to avoid conflicts\r\n\r\n## API Endpoints\r\n\r\n### Status & Health\r\n- `GET /status` - Server status and session information\r\n- `GET /health` - Simple health check\r\n\r\n### Event Capture (Observer)\r\n- `POST /events` - Submit browser events\r\n- `GET /events/{session_id}` - Get events for session\r\n- `GET /events/{session_id}/latest` - Get latest events\r\n\r\n### Browser Control (Actor)\r\n- `POST /commands/{session_id}` - Send commands to browser\r\n- `GET /commands/{session_id}` - Get pending commands\r\n- `DELETE /commands/{session_id}/{command_id}` - Remove command\r\n\r\n### Session Management\r\n- `GET /sessions` - List all sessions\r\n- `POST /sessions` - Create new session\r\n- `GET /sessions/{session_id}` - Get session details\r\n\r\n## Configuration\r\n\r\nThe server can be configured via environment variables:\r\n\r\n```bash\r\nAIBE_PORT=3001 # Server port (default: 3001)\r\nAIBE_DEBUG=true # Enable debug logging\r\nAIBE_LOG_LEVEL=info # Logging level\r\n```\r\n\r\n## Architecture\r\n\r\nAIBE implements a dual-channel architecture:\r\n\r\n1. **Observer Channel**: Browser \u2192 Server (events, screen state)\r\n2. **Actor Channel**: Server \u2192 Browser (commands, actions)\r\n\r\nThis enables AI systems to both learn from human interactions and take autonomous actions.\r\n\r\n## Generic User Framework\r\n\r\nAIBE is designed to support the Generic User Framework (GUA), where:\r\n\r\n- **Task Domain AI**: Focuses on business logic and goals\r\n- **Browser Interaction AI**: Handles web navigation mechanics\r\n- **AIBE Server**: Provides the technical bridge between AI and browser\r\n\r\n## Testing\r\n\r\nThe server includes comprehensive test suites:\r\n\r\n```bash\r\n# Run validation tests\r\npython validate_core.py\r\n\r\n# Start test runner web interface\r\n# Visit http://localhost:3001/test-runner\r\n```\r\n\r\n## Development\r\n\r\n### Project Structure\r\n\r\n```\r\nserver/\r\n\u251c\u2500\u2500 aibe_server/ # Main package\r\n\u2502 \u251c\u2500\u2500 main.py # FastAPI application\r\n\u2502 \u251c\u2500\u2500 session_manager.py\r\n\u2502 \u251c\u2500\u2500 models/ # Pydantic models\r\n\u2502 \u251c\u2500\u2500 middleware/ # Custom middleware\r\n\u2502 \u251c\u2500\u2500 utils/ # Utilities\r\n\u2502 \u251c\u2500\u2500 static/ # Web assets\r\n\u2502 \u2514\u2500\u2500 templates/ # HTML templates\r\n\u251c\u2500\u2500 server.py # Entry point\r\n\u251c\u2500\u2500 install.py # Automatic installer\r\n\u251c\u2500\u2500 pyproject.toml # Package configuration\r\n\u2514\u2500\u2500 requirements.txt # Dependencies\r\n```\r\n\r\n### Running from Source\r\n\r\n```bash\r\n# Using the installer (recommended)\r\npython install.py\r\n\r\n# Or manually\r\npip install -r requirements.txt\r\npython server.py\r\n```\r\n\r\n## Virtual Environment Benefits\r\n\r\nThe automatic installation creates an isolated Python environment that:\r\n\r\n- Prevents conflicts with system Python packages\r\n- Works on systems where users can't install global packages\r\n- Ensures consistent dependency versions\r\n- Makes uninstallation clean (just delete `~/.aibe-server/`)\r\n\r\n## Research Context\r\n\r\nAIBE is part of ongoing research into:\r\n\r\n- **Persistent Cognitive Architectures** for AI systems\r\n- **Human-AI Collaboration** patterns and methodologies \r\n- **Generic User Framework** for universal web interaction\r\n- **Memory Agent** concepts for continuous learning\r\n\r\n## License\r\n\r\nMIT License - See LICENSE file for details.\r\n\r\n## Support\r\n\r\n- **Documentation**: https://paulhanchett.com/aibe/manual\r\n- **Research Papers**: https://paulhanchett.com/research\r\n\r\n## Citation\r\n\r\nIf you use AIBE in research, please cite:\r\n\r\n```bibtex\r\n@software{hanchett2025aibe,\r\n title={AI Browser Extension Interface: Enabling AI Systems to Navigate Web Interfaces},\r\n author={Hanchett, Paul},\r\n year={2025},\r\n url={https://paulhanchett.com/aibe}\r\n}\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "AI Browser Extension Interface Server - enables AI systems to observe and control web browsers",
"version": "0.9.0a4",
"project_urls": {
"Documentation": "https://paulhanchett.com/aibe/docs",
"Homepage": "https://paulhanchett.com/aibe"
},
"split_keywords": [
"ai",
" browser",
" automation",
" generic-user-framework",
" web-interface"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "445d6826b2a8f5ff10672dc2f329f0511b413630439f78978b5f68d72d22ec8a",
"md5": "c3b9da8f2bddaa4b896b11ea34e96e9f",
"sha256": "2bca06d377e7370edf13eeedf191ff08a432e4b6174e137f9fc57fb4210432c3"
},
"downloads": -1,
"filename": "aibe_server-0.9.0a4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3b9da8f2bddaa4b896b11ea34e96e9f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 138741,
"upload_time": "2025-08-16T04:21:28",
"upload_time_iso_8601": "2025-08-16T04:21:28.592431Z",
"url": "https://files.pythonhosted.org/packages/44/5d/6826b2a8f5ff10672dc2f329f0511b413630439f78978b5f68d72d22ec8a/aibe_server-0.9.0a4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 04:21:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "aibe-server"
}
JSON