| Name | kagebunshin JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | AI web automation agent swarm with self-cloning capabilities |
| upload_time | 2025-08-29 04:11:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.13 |
| license | MIT |
| keywords |
agent
ai
automation
browser
web-scraping
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## Kagebunshin 🍥
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
**Kagebunshin** is a web-browsing, research-focused agent swarm with self-cloning capabilities. Built on the foundation of advanced language models, this system enables economically viable parallel web automation.
### Q&A
Q: What does it do?
It works very similar to how ChatGPT agent functions. On top of it, it comes with additional features:
- cloning itself and navigate multiple branches simultaneously
- communicating with each other with the group chat feature: agents can “post” what they are working on their internal group chat, so that there is no working on the same thing, and encourage emergent behaviors.
Q: Why now?
While everyone is focusing on GPT-5’s performance, I looked at GPT-5-nano’s. It matches or even outperforms previous gpt-4.1-mini, at the x5-10 less cost. This means we can use 5 parallel agents with nano with the same cost of running 1 agent with 4.1 mini. As far as I know, GPT agent runs on gpt-4.1-mini (now they must have updated it, right?). This implies, this can be extremely useful when you need quantity over quality, such as data collection, scraping, etc.
Q: Limitations?
1. it is a legion of “dumber” agents. While it can do dumb stuff like aggregating and collecting data, but coming up with novel conclusion must not be done by this guy. We can instead let smarter GPT to do the synthesis.
2. Scalability: On my laptop it works just as fine. However, we don’t know what kind of devils are hiding in the details if we want to scale this up. I have set up comprehensive bot detection evasion, but it might not be enough when it becomes a production level scale.
Please let me know if you have any questions or comments. Thank you!
### Features
- Self-cloning (Hence the name, lol) for parallelized execution
- "Agent Group Chat" for communication between clones, mitigating duplicated work & encouraging emergent behavior
- Tool-augmented agent loop via LangGraph
- Human-like delays, typing, scrolling
- Browser fingerprint and stealth adjustments
- Tab management and PDF handling
## Installation
### From PyPI (Recommended)
```bash
# Using uv (recommended)
uv add kagebunshin
uv run playwright install chromium
# Or using pip
pip install kagebunshin
playwright install chromium
```
### Development Installation
For development or to get the latest features:
```bash
# Using uv
git clone https://github.com/SiwooBae/kagebunshin.git
cd kagebunshin
uv python install 3.13
uv venv -p 3.13
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync
uv run playwright install chromium
# Using pip
git clone https://github.com/SiwooBae/kagebunshin.git
cd kagebunshin
pip install -e .
playwright install chromium
```
### Environment Setup
Set your API key in your environment:
```bash
export OPENAI_API_KEY="your-openai-api-key"
# or for Anthropic (if configured)
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```
## Usage
### Command Line Interface
```bash
# Run the agent (using uv)
uv run -m kagebunshin "Your task description"
# Run with interactive REPL mode
uv run -m kagebunshin --repl
# Reference a markdown file as the task
uv run -m kagebunshin -r @kagebunshin/config/prompts/useful_query_templates/literature_review.md
# Combine custom query with markdown file reference
uv run -m kagebunshin "Execute this task" -r @path/to/template.md
# Available query templates:
# - @kagebunshin/config/prompts/useful_query_templates/literature_review.md
# - @kagebunshin/config/prompts/useful_query_templates/E2E_testing.md
# Or if installed with pip
kagebunshin "Your task"
kagebunshin --repl
kagebunshin -r @path/to/file.md
```
### Programmatic Usage
#### Simple API (Recommended)
The simplified `Agent` class provides comprehensive configuration without needing to edit settings files:
```python
import asyncio
from kagebunshin import Agent
# Simplest usage - uses intelligent defaults
async def main():
agent = Agent(task="Find me some desk toys")
result = await agent.run()
print(result)
asyncio.run(main())
```
##### With Custom LLM
```python
from langchain.chat_models import ChatOpenAI
async def main():
agent = Agent(
task="Find repo stars and analyze trends",
llm=ChatOpenAI(model="gpt-4o-mini", temperature=0)
)
result = await agent.run()
print(result)
asyncio.run(main())
```
##### Full Configuration Example
```python
agent = Agent(
task="Complex research with multiple steps",
# LLM Configuration
llm_model="gpt-5", # Model name
llm_provider="openai", # "openai" or "anthropic"
llm_reasoning_effort="high", # "minimal", "low", "medium", "high"
llm_temperature=0.1, # Temperature (0.0-2.0)
# Summarizer Configuration
summarizer_model="gpt-5-nano", # Cheaper model for summaries
enable_summarization=True, # Enable action summaries
# Browser Configuration
headless=False, # Visible browser
viewport_width=1280, # Browser viewport width
viewport_height=1280, # Browser viewport height
browser_executable_path="/path/chrome", # Custom browser
user_data_dir="~/chrome-profile", # Persistent profile
# Workflow Configuration
recursion_limit=200, # Max recursion depth
max_iterations=150, # Max iterations
timeout=120, # Timeout per operation
# Multi-agent Configuration
group_room="research_team", # Group chat room
username="lead_researcher" # Agent name
)
result = await agent.run()
```
##### Available Parameters
**LLM Configuration:**
- `llm`: Pre-configured LLM instance (optional)
- `llm_model`: Model name (default: "gpt-5-mini")
- `llm_provider`: "openai" or "anthropic" (default: "openai")
- `llm_reasoning_effort`: "minimal", "low", "medium", "high" (default: "low")
- `llm_temperature`: Temperature 0.0-2.0 (default: 1.0)
**Summarizer Configuration:**
- `summarizer_model`: Model for summaries (default: "gpt-5-nano")
- `summarizer_provider`: Provider for summarizer (default: "openai")
- `enable_summarization`: Enable action summaries (default: False)
**Browser Configuration:**
- `headless`: Run in headless mode (default: False)
- `viewport_width`: Browser width (default: 1280)
- `viewport_height`: Browser height (default: 1280)
- `browser_executable_path`: Custom browser path (default: auto-detect)
- `user_data_dir`: Persistent profile directory (default: temporary)
**Workflow Configuration:**
- `recursion_limit`: Max recursion depth (default: 150)
- `max_iterations`: Max iterations per task (default: 100)
- `timeout`: Timeout per operation in seconds (default: 60)
**Multi-agent Configuration:**
- `group_room`: Group chat room name (default: "lobby")
- `username`: Agent name (default: auto-generated)
#### Advanced API
For more control over the browser lifecycle, use the lower-level `KageBunshinAgent`:
```python
from kagebunshin import KageBunshinAgent
from playwright.async_api import async_playwright
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch()
context = await browser.new_context()
orchestrator = await KageBunshinAgent.create(context)
async for chunk in orchestrator.astream("Your task"):
print(chunk)
await browser.close()
```
### BrowseComp eval
Evaluate Kagebunshin on OpenAI's BrowseComp benchmark.
Prereqs:
- Ensure Playwright browsers are installed (see Installation). If using Chromium: `uv run playwright install chromium`.
- Set `OPENAI_API_KEY` for the grader model.
Quick start (uv):
```bash
uv run -m evals.run_browsercomp --headless --num-examples 20 --grader-model gpt-5 --grader-provider openai
```
Quick start (pip):
```bash
python -m evals.run_browsercomp --headless --num-examples 20 --grader-model gpt-5 --grader-provider openai
```
Options:
- `--num-examples N`: sample N problems from the test set. When provided, `--n-repeats` must remain 1.
- `--n-repeats N`: repeat each example N times (only when running the full set).
- `--headless`: run the browser without a visible window.
- `--browser {chromium,chrome}`: choose Playwright Chromium or your local Chrome.
- `--grader-model`, `--grader-provider`: LLM used for grading (default `gpt-5` on `openai`).
- `--report PATH`: path to save the HTML report (defaults to `runs/browsecomp-report-<timestamp>.html`).
Output:
- Prints aggregate metrics (e.g., accuracy) to stdout.
- Saves a standalone HTML report with prompts, responses, and per-sample scores.
## Configuration
Edit `kagebunshin/config/settings.py` to customize:
- **LLM Settings**: Model/provider, temperature, reasoning effort
- **Browser Settings**: Executable path, user data directory, permissions
- **Stealth Features**: Fingerprint profiles, human behavior simulation
- **Group Chat**: Redis connection settings for agent coordination
- **Performance**: Concurrency limits, timeouts, delays
## Development
### Setting up for development
```bash
git clone https://github.com/SiwooBae/kagebunshin.git
cd kagebunshin
uv sync --all-extras
uv run playwright install chromium
```
### Code Quality
The project includes tools for maintaining code quality:
```bash
# Format code
uv run black .
uv run isort .
# Lint code
uv run flake8 kagebunshin/
# Type checking
uv run mypy kagebunshin/
```
### Testing
Kagebunshin includes a comprehensive unit test suite following TDD (Test-Driven Development) principles:
```bash
# Run all tests
uv run pytest
# Run tests with verbose output
uv run pytest -v
# Run specific test module
uv run pytest tests/core/test_agent.py
# Run tests with coverage report
uv run pytest --cov=kagebunshin
# Run tests in watch mode (requires pytest-watch)
ptw -- --testmon
```
#### Test Structure
The test suite covers all major components with 155 comprehensive tests:
```
tests/
├── conftest.py # Shared fixtures and test configuration
├── core/ # Core functionality tests (63 tests)
│ ├── test_agent.py # KageBunshinAgent initialization & workflow (15 tests)
│ ├── test_state.py # State models and validation (14 tests)
│ └── test_state_manager.py # Browser operations & page management (34 tests)
├── tools/ # Agent tools tests (11 tests)
│ └── test_delegation.py # Shadow clone delegation system
├── communication/ # Group chat tests (17 tests)
│ └── test_group_chat.py # Redis-based communication
├── utils/ # Utility function tests (35 tests)
│ ├── test_formatting.py # Text/HTML formatting & normalization (27 tests)
│ └── test_naming.py # Agent name generation (8 tests)
└── automation/ # Browser automation tests (29 tests)
└── test_behavior.py # Human behavior simulation
# Configuration files (in project root):
pytest.ini # Pytest configuration with asyncio support
```
## Project Structure
Kagebunshin features a clean, modular architecture optimized for readability and extensibility:
```
kagebunshin/
├── core/ # 🧠 Core agent functionality
│ ├── agent.py # Main KageBunshinAgent orchestrator
│ ├── state.py # State models and data structures
│ └── state_manager.py # Browser state operations
│
├── automation/ # 🤖 Browser automation & stealth
│ ├── behavior.py # Human behavior simulation
│ ├── fingerprinting.py # Browser fingerprint evasion
│ └── browser/ # Browser-specific utilities
│
├── tools/ # 🔧 Agent tools & capabilities
│ └── delegation.py # Agent cloning and delegation
│
├── communication/ # 💬 Agent coordination
│ └── group_chat.py # Redis-based group chat
│
├── cli/ # 🖥️ Command-line interface
│ ├── runner.py # CLI runner and REPL
│ └── ui/ # Future UI components
│
├── config/ # ⚙️ Configuration management
│ ├── settings.py # All configuration settings
│ └── prompts/ # System prompts and query templates
│ ├── kagebunshin_system_prompt.md # Main system prompt
│ ├── kagebunshin_system_prompt_v2.md # Alternative system prompt
│ ├── tell_the_cur_state.md # State description prompt
│ └── useful_query_templates/ # Pre-built query templates
│ ├── literature_review.md # Academic literature review
│ └── E2E_testing.md # End-to-end testing
│
└── utils/ # 🛠️ Shared utilities
├── formatting.py # HTML/text formatting for LLM
├── logging.py # Logging utilities
└── naming.py # Agent name generation
```
### Key Components
- **🧠 Core Agent**: Orchestrates web automation tasks using LangGraph
- **🤖 Automation**: Human-like behavior simulation and stealth browsing
- **🔧 Tools**: Agent delegation system for parallel task execution
- **💬 Communication**: Redis-based group chat for agent coordination
- **🖥️ CLI**: Interactive command-line interface with streaming updates
## Contributing
We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [LangGraph](https://github.com/langchain-ai/langgraph) for agent orchestration
- Uses [Playwright](https://playwright.dev/) for browser automation
- Inspired by the need for cost-effective parallel web automation
Raw data
{
"_id": null,
"home_page": null,
"name": "kagebunshin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "agent, ai, automation, browser, web-scraping",
"author": null,
"author_email": "Siwoo Bae <cymetric1@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/bf/33/dc227207b53a4eaf93dc5c51a46d5d13ac6b2c969016568ae86b8883a1c4/kagebunshin-0.1.1.tar.gz",
"platform": null,
"description": "## Kagebunshin \ud83c\udf65\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\n**Kagebunshin** is a web-browsing, research-focused agent swarm with self-cloning capabilities. Built on the foundation of advanced language models, this system enables economically viable parallel web automation.\n\n### Q&A\n\nQ: What does it do?\n\nIt works very similar to how ChatGPT agent functions. On top of it, it comes with additional features:\n- cloning itself and navigate multiple branches simultaneously\n- \u2060communicating with each other with the group chat feature: agents can \u201cpost\u201d what they are working on their internal group chat, so that there is no working on the same thing, and encourage emergent behaviors.\n\nQ: Why now?\n\nWhile everyone is focusing on GPT-5\u2019s performance, I looked at GPT-5-nano\u2019s. It matches or even outperforms previous gpt-4.1-mini, at the x5-10 less cost. This means we can use 5 parallel agents with nano with the same cost of running 1 agent with 4.1 mini. As far as I know, GPT agent runs on gpt-4.1-mini (now they must have updated it, right?). This implies, this can be extremely useful when you need quantity over quality, such as data collection, scraping, etc.\n\nQ: Limitations?\n1. it is a legion of \u201cdumber\u201d agents. While it can do dumb stuff like aggregating and collecting data, but coming up with novel conclusion must not be done by this guy. We can instead let smarter GPT to do the synthesis.\n2. Scalability: On my laptop it works just as fine. However, we don\u2019t know what kind of devils are hiding in the details if we want to scale this up. I have set up comprehensive bot detection evasion, but it might not be enough when it becomes a production level scale.\n\nPlease let me know if you have any questions or comments. Thank you!\n\n### Features\n- Self-cloning (Hence the name, lol) for parallelized execution\n- \"Agent Group Chat\" for communication between clones, mitigating duplicated work & encouraging emergent behavior\n- Tool-augmented agent loop via LangGraph\n- Human-like delays, typing, scrolling\n- Browser fingerprint and stealth adjustments\n- Tab management and PDF handling\n\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Using uv (recommended)\nuv add kagebunshin\nuv run playwright install chromium\n\n# Or using pip\npip install kagebunshin\nplaywright install chromium\n```\n\n### Development Installation\n\nFor development or to get the latest features:\n\n```bash\n# Using uv\ngit clone https://github.com/SiwooBae/kagebunshin.git\ncd kagebunshin\nuv python install 3.13\nuv venv -p 3.13\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\nuv sync\nuv run playwright install chromium\n\n# Using pip\ngit clone https://github.com/SiwooBae/kagebunshin.git\ncd kagebunshin\npip install -e .\nplaywright install chromium\n```\n\n### Environment Setup\n\nSet your API key in your environment:\n```bash\nexport OPENAI_API_KEY=\"your-openai-api-key\"\n# or for Anthropic (if configured)\nexport ANTHROPIC_API_KEY=\"your-anthropic-api-key\"\n```\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Run the agent (using uv)\nuv run -m kagebunshin \"Your task description\"\n\n# Run with interactive REPL mode\nuv run -m kagebunshin --repl\n\n# Reference a markdown file as the task\nuv run -m kagebunshin -r @kagebunshin/config/prompts/useful_query_templates/literature_review.md\n\n# Combine custom query with markdown file reference\nuv run -m kagebunshin \"Execute this task\" -r @path/to/template.md\n\n# Available query templates:\n# - @kagebunshin/config/prompts/useful_query_templates/literature_review.md\n# - @kagebunshin/config/prompts/useful_query_templates/E2E_testing.md\n\n# Or if installed with pip\nkagebunshin \"Your task\"\nkagebunshin --repl\nkagebunshin -r @path/to/file.md\n```\n\n### Programmatic Usage\n\n#### Simple API (Recommended)\n\nThe simplified `Agent` class provides comprehensive configuration without needing to edit settings files:\n\n```python\nimport asyncio\nfrom kagebunshin import Agent\n\n# Simplest usage - uses intelligent defaults\nasync def main():\n agent = Agent(task=\"Find me some desk toys\")\n result = await agent.run()\n print(result)\n\nasyncio.run(main())\n```\n\n##### With Custom LLM\n\n```python\nfrom langchain.chat_models import ChatOpenAI\n\nasync def main():\n agent = Agent(\n task=\"Find repo stars and analyze trends\",\n llm=ChatOpenAI(model=\"gpt-4o-mini\", temperature=0)\n )\n result = await agent.run()\n print(result)\n\nasyncio.run(main())\n```\n\n##### Full Configuration Example\n\n```python\nagent = Agent(\n task=\"Complex research with multiple steps\",\n \n # LLM Configuration\n llm_model=\"gpt-5\", # Model name\n llm_provider=\"openai\", # \"openai\" or \"anthropic\"\n llm_reasoning_effort=\"high\", # \"minimal\", \"low\", \"medium\", \"high\"\n llm_temperature=0.1, # Temperature (0.0-2.0)\n \n # Summarizer Configuration\n summarizer_model=\"gpt-5-nano\", # Cheaper model for summaries\n enable_summarization=True, # Enable action summaries\n \n # Browser Configuration\n headless=False, # Visible browser\n viewport_width=1280, # Browser viewport width\n viewport_height=1280, # Browser viewport height\n browser_executable_path=\"/path/chrome\", # Custom browser\n user_data_dir=\"~/chrome-profile\", # Persistent profile\n \n # Workflow Configuration\n recursion_limit=200, # Max recursion depth\n max_iterations=150, # Max iterations\n timeout=120, # Timeout per operation\n \n # Multi-agent Configuration\n group_room=\"research_team\", # Group chat room\n username=\"lead_researcher\" # Agent name\n)\nresult = await agent.run()\n```\n\n##### Available Parameters\n\n**LLM Configuration:**\n- `llm`: Pre-configured LLM instance (optional)\n- `llm_model`: Model name (default: \"gpt-5-mini\")\n- `llm_provider`: \"openai\" or \"anthropic\" (default: \"openai\")\n- `llm_reasoning_effort`: \"minimal\", \"low\", \"medium\", \"high\" (default: \"low\")\n- `llm_temperature`: Temperature 0.0-2.0 (default: 1.0)\n\n**Summarizer Configuration:**\n- `summarizer_model`: Model for summaries (default: \"gpt-5-nano\")\n- `summarizer_provider`: Provider for summarizer (default: \"openai\")\n- `enable_summarization`: Enable action summaries (default: False)\n\n**Browser Configuration:**\n- `headless`: Run in headless mode (default: False)\n- `viewport_width`: Browser width (default: 1280)\n- `viewport_height`: Browser height (default: 1280)\n- `browser_executable_path`: Custom browser path (default: auto-detect)\n- `user_data_dir`: Persistent profile directory (default: temporary)\n\n**Workflow Configuration:**\n- `recursion_limit`: Max recursion depth (default: 150)\n- `max_iterations`: Max iterations per task (default: 100)\n- `timeout`: Timeout per operation in seconds (default: 60)\n\n**Multi-agent Configuration:**\n- `group_room`: Group chat room name (default: \"lobby\")\n- `username`: Agent name (default: auto-generated)\n\n#### Advanced API\n\nFor more control over the browser lifecycle, use the lower-level `KageBunshinAgent`:\n\n```python\nfrom kagebunshin import KageBunshinAgent\nfrom playwright.async_api import async_playwright\n\nasync def main():\n async with async_playwright() as p:\n browser = await p.chromium.launch()\n context = await browser.new_context()\n \n orchestrator = await KageBunshinAgent.create(context)\n async for chunk in orchestrator.astream(\"Your task\"):\n print(chunk)\n \n await browser.close()\n```\n\n### BrowseComp eval\n\nEvaluate Kagebunshin on OpenAI's BrowseComp benchmark.\n\nPrereqs:\n- Ensure Playwright browsers are installed (see Installation). If using Chromium: `uv run playwright install chromium`.\n- Set `OPENAI_API_KEY` for the grader model.\n\nQuick start (uv):\n```bash\nuv run -m evals.run_browsercomp --headless --num-examples 20 --grader-model gpt-5 --grader-provider openai\n```\n\nQuick start (pip):\n```bash\npython -m evals.run_browsercomp --headless --num-examples 20 --grader-model gpt-5 --grader-provider openai\n```\n\nOptions:\n- `--num-examples N`: sample N problems from the test set. When provided, `--n-repeats` must remain 1.\n- `--n-repeats N`: repeat each example N times (only when running the full set).\n- `--headless`: run the browser without a visible window.\n- `--browser {chromium,chrome}`: choose Playwright Chromium or your local Chrome.\n- `--grader-model`, `--grader-provider`: LLM used for grading (default `gpt-5` on `openai`).\n- `--report PATH`: path to save the HTML report (defaults to `runs/browsecomp-report-<timestamp>.html`).\n\nOutput:\n- Prints aggregate metrics (e.g., accuracy) to stdout.\n- Saves a standalone HTML report with prompts, responses, and per-sample scores.\n\n## Configuration\n\nEdit `kagebunshin/config/settings.py` to customize:\n\n- **LLM Settings**: Model/provider, temperature, reasoning effort\n- **Browser Settings**: Executable path, user data directory, permissions\n- **Stealth Features**: Fingerprint profiles, human behavior simulation\n- **Group Chat**: Redis connection settings for agent coordination\n- **Performance**: Concurrency limits, timeouts, delays\n\n## Development\n\n### Setting up for development\n\n```bash\ngit clone https://github.com/SiwooBae/kagebunshin.git\ncd kagebunshin\nuv sync --all-extras\nuv run playwright install chromium\n```\n\n### Code Quality\n\nThe project includes tools for maintaining code quality:\n\n```bash\n# Format code\nuv run black .\nuv run isort .\n\n# Lint code \nuv run flake8 kagebunshin/\n\n# Type checking\nuv run mypy kagebunshin/\n```\n\n### Testing\n\nKagebunshin includes a comprehensive unit test suite following TDD (Test-Driven Development) principles:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with verbose output\nuv run pytest -v\n\n# Run specific test module\nuv run pytest tests/core/test_agent.py\n\n# Run tests with coverage report\nuv run pytest --cov=kagebunshin\n\n# Run tests in watch mode (requires pytest-watch)\nptw -- --testmon\n```\n\n#### Test Structure\n\nThe test suite covers all major components with 155 comprehensive tests:\n\n```\ntests/\n\u251c\u2500\u2500 conftest.py # Shared fixtures and test configuration\n\u251c\u2500\u2500 core/ # Core functionality tests (63 tests)\n\u2502 \u251c\u2500\u2500 test_agent.py # KageBunshinAgent initialization & workflow (15 tests)\n\u2502 \u251c\u2500\u2500 test_state.py # State models and validation (14 tests)\n\u2502 \u2514\u2500\u2500 test_state_manager.py # Browser operations & page management (34 tests)\n\u251c\u2500\u2500 tools/ # Agent tools tests (11 tests)\n\u2502 \u2514\u2500\u2500 test_delegation.py # Shadow clone delegation system\n\u251c\u2500\u2500 communication/ # Group chat tests (17 tests)\n\u2502 \u2514\u2500\u2500 test_group_chat.py # Redis-based communication\n\u251c\u2500\u2500 utils/ # Utility function tests (35 tests)\n\u2502 \u251c\u2500\u2500 test_formatting.py # Text/HTML formatting & normalization (27 tests)\n\u2502 \u2514\u2500\u2500 test_naming.py # Agent name generation (8 tests)\n\u2514\u2500\u2500 automation/ # Browser automation tests (29 tests)\n \u2514\u2500\u2500 test_behavior.py # Human behavior simulation\n\n# Configuration files (in project root):\npytest.ini # Pytest configuration with asyncio support\n```\n## Project Structure\n\nKagebunshin features a clean, modular architecture optimized for readability and extensibility:\n\n```\nkagebunshin/\n\u251c\u2500\u2500 core/ # \ud83e\udde0 Core agent functionality\n\u2502 \u251c\u2500\u2500 agent.py # Main KageBunshinAgent orchestrator\n\u2502 \u251c\u2500\u2500 state.py # State models and data structures\n\u2502 \u2514\u2500\u2500 state_manager.py # Browser state operations\n\u2502\n\u251c\u2500\u2500 automation/ # \ud83e\udd16 Browser automation & stealth\n\u2502 \u251c\u2500\u2500 behavior.py # Human behavior simulation\n\u2502 \u251c\u2500\u2500 fingerprinting.py # Browser fingerprint evasion\n\u2502 \u2514\u2500\u2500 browser/ # Browser-specific utilities\n\u2502\n\u251c\u2500\u2500 tools/ # \ud83d\udd27 Agent tools & capabilities\n\u2502 \u2514\u2500\u2500 delegation.py # Agent cloning and delegation\n\u2502\n\u251c\u2500\u2500 communication/ # \ud83d\udcac Agent coordination\n\u2502 \u2514\u2500\u2500 group_chat.py # Redis-based group chat\n\u2502\n\u251c\u2500\u2500 cli/ # \ud83d\udda5\ufe0f Command-line interface\n\u2502 \u251c\u2500\u2500 runner.py # CLI runner and REPL\n\u2502 \u2514\u2500\u2500 ui/ # Future UI components\n\u2502\n\u251c\u2500\u2500 config/ # \u2699\ufe0f Configuration management\n\u2502 \u251c\u2500\u2500 settings.py # All configuration settings\n\u2502 \u2514\u2500\u2500 prompts/ # System prompts and query templates\n\u2502 \u251c\u2500\u2500 kagebunshin_system_prompt.md # Main system prompt\n\u2502 \u251c\u2500\u2500 kagebunshin_system_prompt_v2.md # Alternative system prompt \n\u2502 \u251c\u2500\u2500 tell_the_cur_state.md # State description prompt\n\u2502 \u2514\u2500\u2500 useful_query_templates/ # Pre-built query templates\n\u2502 \u251c\u2500\u2500 literature_review.md # Academic literature review\n\u2502 \u2514\u2500\u2500 E2E_testing.md # End-to-end testing\n\u2502\n\u2514\u2500\u2500 utils/ # \ud83d\udee0\ufe0f Shared utilities\n \u251c\u2500\u2500 formatting.py # HTML/text formatting for LLM\n \u251c\u2500\u2500 logging.py # Logging utilities\n \u2514\u2500\u2500 naming.py # Agent name generation\n```\n\n### Key Components\n\n- **\ud83e\udde0 Core Agent**: Orchestrates web automation tasks using LangGraph\n- **\ud83e\udd16 Automation**: Human-like behavior simulation and stealth browsing\n- **\ud83d\udd27 Tools**: Agent delegation system for parallel task execution\n- **\ud83d\udcac Communication**: Redis-based group chat for agent coordination\n- **\ud83d\udda5\ufe0f CLI**: Interactive command-line interface with streaming updates\n\n## Contributing\n\nWe welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [LangGraph](https://github.com/langchain-ai/langgraph) for agent orchestration\n- Uses [Playwright](https://playwright.dev/) for browser automation\n- Inspired by the need for cost-effective parallel web automation\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI web automation agent swarm with self-cloning capabilities",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/SiwooBae/kagebunshin",
"Issues": "https://github.com/SiwooBae/kagebunshin/issues",
"Repository": "https://github.com/SiwooBae/kagebunshin"
},
"split_keywords": [
"agent",
" ai",
" automation",
" browser",
" web-scraping"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bd99425d988ca4f1616836471b01629243465542dcf82f75dcbc36a2c94ad55f",
"md5": "0aa726865c4a02416b5636a0d55c98bc",
"sha256": "96f992490f1cfbcfef82f3ef2b9c2228b8035487cb6411bf57b6f8d8a189e60d"
},
"downloads": -1,
"filename": "kagebunshin-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0aa726865c4a02416b5636a0d55c98bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 133290,
"upload_time": "2025-08-29T04:11:41",
"upload_time_iso_8601": "2025-08-29T04:11:41.743855Z",
"url": "https://files.pythonhosted.org/packages/bd/99/425d988ca4f1616836471b01629243465542dcf82f75dcbc36a2c94ad55f/kagebunshin-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bf33dc227207b53a4eaf93dc5c51a46d5d13ac6b2c969016568ae86b8883a1c4",
"md5": "027b5265e82496cbcbdc704e59e0d309",
"sha256": "32dfdafd024f95166e42412e050e3395ed6f27adabda486deaa05269b39abed7"
},
"downloads": -1,
"filename": "kagebunshin-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "027b5265e82496cbcbdc704e59e0d309",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 296350,
"upload_time": "2025-08-29T04:11:43",
"upload_time_iso_8601": "2025-08-29T04:11:43.297377Z",
"url": "https://files.pythonhosted.org/packages/bf/33/dc227207b53a4eaf93dc5c51a46d5d13ac6b2c969016568ae86b8883a1c4/kagebunshin-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-29 04:11:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SiwooBae",
"github_project": "kagebunshin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kagebunshin"
}
