| Name | pywen-agent JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | LLM-based agent for general purpose tasks |
| upload_time | 2025-08-05 06:28:49 |
| maintainer | None |
| docs_url | None |
| author | PAMPAS-Lab |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
agent
cli
llm
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pywen
[](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)
[**δΈζη**](README_ch.md) | **English**
**Pywen** is a Python CLI tool based on **Qwen3-Coder**, designed specifically for intelligent software engineering tasks. It provides a conversational interface that can understand natural language instructions and execute complex development workflows through an advanced agent system.
## π― Project Background
Pywen is built on the [**Qwen3-Coder**](https://github.com/QwenLM/Qwen3-Coder) large language model, aiming to provide developers with an efficient and intelligent code assistant. The project is primarily adapted from [**Qwen-Code**](https://github.com/QwenLM/qwen-code), with deep optimizations for Python developers and the Qwen3-Coder model.
### Why Choose Qwen3-Coder?
- π **Code Specialization**: Qwen3-Coder excels in code generation, understanding, and debugging
- β‘ **Efficient Inference**: Optimized model architecture providing fast responses
- π§ **Engineering Practicality**: Specifically trained for real-world software development scenarios
**Project Status:** The project is still under active development. We welcome your help in improving Pywen.
## Differences from Other Code Agent CLIs
Pywen is a Python-based CLI tool with excellent Python ecosystem compatibility and developer-friendliness. It provides a **transparent, modular architecture** that allows researchers and developers to easily modify, extend, and analyze, making it an ideal platform for **researching AI Agent architectures, conducting ablation studies, and developing new Agent capabilities**. This **research-friendly design** enables academia and the open-source community to more easily contribute to foundational Agent frameworks and build innovative applications, facilitating continuous breakthroughs in the rapidly evolving AI Agent field.
## β¨ Features
- π€ **Qwen3-Coder-Plus Powered**: Based on Alibaba Cloud's latest code-specialized large model
- π¦ **Modular**: Built on modular architecture, extensible and customizable (future support for multi-agent frameworks)
- π οΈ **Rich Tool Ecosystem**: File editing, bash execution, sequential thinking, and more
- π **Trajectory Recording**: Detailed logging of all Agent operations for debugging and analysis
- βοΈ **Smart Configuration**: Automatic guided configuration on first run, supports environment variables
- π **Session Statistics**: Real-time tracking of API calls, tool usage, and token consumption
## π Quick Start
### Installation
We strongly recommend using [uv](https://docs.astral.sh/uv/) to set up the project:
```bash
git clone https://github.com/PAMPAS-Lab/Pywen.git
cd Pywen
uv venv
uv sync --all-extras
# linux/macos
source .venv/bin/activate
# windows
.venv\Scripts\activate
```
### First Use
Simply run the `pywen` command to start:
```bash
pywen
```
If it's your first run and there's no configuration file, Pywen will automatically start the configuration wizard:
```
βββββββ βββ ββββββ βββββββββββββββ βββ
ββββββββββββ βββββββ ββββββββββββββββ βββ
ββββββββ βββββββ βββ ββ βββββββββ ββββββ βββ
βββββββ βββββ ββββββββββββββββ ββββββββββ
βββ βββ βββββββββββββββββββββ ββββββ
βββ βββ ββββββββ βββββββββββ βββββ
Configuration file not found, starting setup wizard...
API Key: [Enter your Qwen API key]
Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
Model: qwen3-coder-plus
...
β
Configuration saved to pywen_config.json
```
After configuration is complete, you can start using Pywen!
### Basic Usage
Once you enter the Pywen command-line interface, you can:
```bash
# File operations
> Create a Python script to calculate Fibonacci sequence
> Refactor functions in main.py to make them more efficient
# Code analysis and debugging
> Fix bugs in this project and add unit tests
> Analyze performance bottlenecks in my code
# Project management
> Create a new Flask web application with proper structure
> Add comprehensive documentation to this codebase
```
## π User Guide
### Command Line Interface
#### Available Commands
```bash
# System commands
/help, /? - Show help information
/clear - Clear screen and conversation history
/status - Show agent status
/config - Show current configuration
/stats - Check session statistics (API calls, tokens, etc.)
/quit, /exit - Exit Pywen
# Special commands
@<file> - Include file content in prompt
!<command> - Execute shell command
# Keyboard shortcuts
Ctrl+Y - Toggle YOLO mode (auto-approve all operations - use with caution!)
# Direct input of task descriptions to execute agent
```
### YOLO Mode
**Use with caution:**
- Press `Ctrl+Y` to toggle YOLO mode
- **Default behavior**: All tool calls require user confirmation for safety
- In YOLO mode, all tool calls are automatically approved without user confirmation
- This speeds up execution but removes safety checks
- Mode status is displayed in the interface
- You can also type 'a' (always) when prompted for tool confirmation to enable YOLO mode
### Configuration Management
Pywen uses the `pywen_config.json` file for configuration:
```json
{
"default_provider": "qwen",
"max_steps": 20,
"enable_lakeview": false,
"model_providers": {
"qwen": {
"api_key": "your-qwen-api-key",
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen3-coder-plus",
"max_tokens": 4096,
"temperature": 0.5
}
}
}
```
**Configuration Priority:**
1. Command line arguments (highest)
2. Configuration file values
3. Environment variables
4. Default values (lowest)
### Environment Variables
You can set API keys through environment variables:
```bash
# Qwen (required)
export QWEN_API_KEY="your-qwen-api-key"
# Tool API Keys (optional but recommended)
export SERPER_API_KEY="your-serper-api-key" # For web search
export JINA_API_KEY="your-jina-api-key" # For content reading
# Other supported providers
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```
### Getting API Keys
**Serper API (Web Search):**
1. Visit [serper.dev](https://serper.dev/)
2. Sign up for a free account
3. Get your API key from the dashboard
**Jina API (Content Reading):**
1. Visit [jina.ai](https://jina.ai/)
2. Sign up for a free account
3. Get your API key from the dashboard
## π οΈ Available Tools
Pywen provides a comprehensive toolkit for software development:
- **File Operations**: Create, edit, read, and manage files
- **Bash Execution**: Run shell commands and scripts
- **Sequential Thinking**: Structured problem-solving approach
- **Task Completion**: Mark tasks as complete with summaries
- **JSON Operations**: Parse and manipulate JSON data
For detailed information about all available tools and their capabilities, see [docs/tools.md](docs/tools.md).
## π Trajectory Recording
Pywen automatically records detailed execution trajectories for debugging and analysis:
```bash
# Trajectory files are automatically saved to trajectories/ directory
trajectories/trajectory_xxxxxx.json
```
Trajectory files contain:
- **LLM Interactions**: All messages, responses, and tool calls
- **Agent Steps**: State transitions and decision points
- **Tool Usage**: Which tools were called and their results
- **Metadata**: Timestamps, token usage, and execution metrics
## π Session Statistics
Monitor your usage with real-time statistics:
```bash
> /stats
```
Tracks:
- API calls and token consumption
- Tool usage patterns
- Session duration
- Model performance metrics
## π€ Contributing
We welcome contributions to Pywen! Here's how to get started:
1. Fork the repository
2. Set up the development environment:
```bash
git clone https://github.com/your-username/Pywen.git
cd Pywen
uv venv
uv sync --all-extras
# linux/macos
source .venv/bin/activate
# windows
.venv\Scripts\activate
```
3. Create a feature branch
4. Make your changes and add tests
5. Submit a pull request
### Development Guidelines
- Follow PEP 8 style guidelines
- Add tests for new features
- Update documentation as needed
- Use type hints appropriately
- Ensure all tests pass before submitting
## π Requirements
- Python 3.12+
- Qwen API key (recommended) or other supported LLM provider API keys
- Internet connection for API access
## π§ Troubleshooting
### Common Issues
**Configuration Issues:**
```bash
# Re-run configuration wizard
rm pywen_config.json
pywen
```
**API Key Issues:**
```bash
# Verify your API key is set
echo $QWEN_API_KEY
# Check configuration in Pywen
> /config
```
## π Acknowledgments
We thank:
- **Google** for the [Gemini CLI](https://github.com/google-gemini/gemini-cli) project, which provided agent execution logic and rich tool ecosystem libraries for this project
- **Alibaba Cloud Qwen Team** for providing the powerful [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) model and [Qwen-Code](https://github.com/QwenLM/qwen-code) reference implementation
- **ByteDance** for the [trae-agent](https://github.com/bytedance/trae-agent) project, which provided valuable foundational architecture for this project
## π License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
**Pywen - Making the power of Qwen3-Coder accessible for intelligent software development!** π
**PAMPAS-Lab - Dedicated to breakthroughs in large model agent frameworks, bridging AI research and applications!** π
Raw data
{
"_id": null,
"home_page": null,
"name": "pywen-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "agent, cli, llm",
"author": "PAMPAS-Lab",
"author_email": "CHEN LONGRONG <longrongchen@163.com>, XUE YIBO <yiboxue@163.com>",
"download_url": "https://files.pythonhosted.org/packages/23/07/72b4e146c3aa0adc8b0af2e46574a2f8e0e2a4b4c8fec07c915687010719/pywen_agent-0.1.0.tar.gz",
"platform": null,
"description": "# Pywen\n\n[](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)\n\n\n[**\u4e2d\u6587\u7248**](README_ch.md) | **English**\n\n**Pywen** is a Python CLI tool based on **Qwen3-Coder**, designed specifically for intelligent software engineering tasks. It provides a conversational interface that can understand natural language instructions and execute complex development workflows through an advanced agent system.\n\n## \ud83c\udfaf Project Background\n\nPywen is built on the [**Qwen3-Coder**](https://github.com/QwenLM/Qwen3-Coder) large language model, aiming to provide developers with an efficient and intelligent code assistant. The project is primarily adapted from [**Qwen-Code**](https://github.com/QwenLM/qwen-code), with deep optimizations for Python developers and the Qwen3-Coder model.\n\n### Why Choose Qwen3-Coder?\n\n- \ud83d\ude80 **Code Specialization**: Qwen3-Coder excels in code generation, understanding, and debugging\n- \u26a1 **Efficient Inference**: Optimized model architecture providing fast responses\n- \ud83d\udd27 **Engineering Practicality**: Specifically trained for real-world software development scenarios\n\n**Project Status:** The project is still under active development. We welcome your help in improving Pywen.\n\n## Differences from Other Code Agent CLIs\n\nPywen is a Python-based CLI tool with excellent Python ecosystem compatibility and developer-friendliness. It provides a **transparent, modular architecture** that allows researchers and developers to easily modify, extend, and analyze, making it an ideal platform for **researching AI Agent architectures, conducting ablation studies, and developing new Agent capabilities**. This **research-friendly design** enables academia and the open-source community to more easily contribute to foundational Agent frameworks and build innovative applications, facilitating continuous breakthroughs in the rapidly evolving AI Agent field.\n\n## \u2728 Features\n\n- \ud83e\udd16 **Qwen3-Coder-Plus Powered**: Based on Alibaba Cloud's latest code-specialized large model\n- \ud83d\udce6 **Modular**: Built on modular architecture, extensible and customizable (future support for multi-agent frameworks)\n- \ud83d\udee0\ufe0f **Rich Tool Ecosystem**: File editing, bash execution, sequential thinking, and more\n- \ud83d\udcca **Trajectory Recording**: Detailed logging of all Agent operations for debugging and analysis\n- \u2699\ufe0f **Smart Configuration**: Automatic guided configuration on first run, supports environment variables\n- \ud83d\udcc8 **Session Statistics**: Real-time tracking of API calls, tool usage, and token consumption\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\nWe strongly recommend using [uv](https://docs.astral.sh/uv/) to set up the project:\n\n```bash\ngit clone https://github.com/PAMPAS-Lab/Pywen.git\ncd Pywen\nuv venv\nuv sync --all-extras\n\n# linux/macos\nsource .venv/bin/activate\n\n# windows\n.venv\\Scripts\\activate\n```\n\n### First Use\n\nSimply run the `pywen` command to start:\n\n```bash\npywen\n```\n\nIf it's your first run and there's no configuration file, Pywen will automatically start the configuration wizard:\n\n```\n\u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557 \u2588\u2588\u2557\u2588\u2588\u2557 \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2557 \u2588\u2588\u2551\n\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u255a\u2588\u2588\u2557 \u2588\u2588\u2554\u255d\u2588\u2588\u2551 \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255d\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2551\n\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255d \u255a\u2588\u2588\u2588\u2588\u2554\u255d \u2588\u2588\u2551 \u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\n\u2588\u2588\u2554\u2550\u2550\u2550\u255d \u255a\u2588\u2588\u2554\u255d \u2588\u2588\u2551\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u255d \u2588\u2588\u2551\u255a\u2588\u2588\u2557\u2588\u2588\u2551\n\u2588\u2588\u2551 \u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2554\u2588\u2588\u2588\u2554\u255d\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2551\n\u255a\u2550\u255d \u255a\u2550\u255d \u255a\u2550\u2550\u255d\u255a\u2550\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d \u255a\u2550\u2550\u2550\u255d\n\nConfiguration file not found, starting setup wizard...\n\nAPI Key: [Enter your Qwen API key]\nBase URL: https://dashscope.aliyuncs.com/compatible-mode/v1\nModel: qwen3-coder-plus\n...\n\n\u2705 Configuration saved to pywen_config.json\n```\n\nAfter configuration is complete, you can start using Pywen!\n\n### Basic Usage\n\nOnce you enter the Pywen command-line interface, you can:\n\n```bash\n# File operations\n> Create a Python script to calculate Fibonacci sequence\n> Refactor functions in main.py to make them more efficient\n\n# Code analysis and debugging\n> Fix bugs in this project and add unit tests\n> Analyze performance bottlenecks in my code\n\n# Project management\n> Create a new Flask web application with proper structure\n> Add comprehensive documentation to this codebase\n```\n\n## \ud83d\udcd6 User Guide\n\n### Command Line Interface\n\n#### Available Commands\n\n```bash\n# System commands\n/help, /? - Show help information\n/clear - Clear screen and conversation history\n/status - Show agent status\n/config - Show current configuration\n/stats - Check session statistics (API calls, tokens, etc.)\n/quit, /exit - Exit Pywen\n\n# Special commands\n@<file> - Include file content in prompt\n!<command> - Execute shell command\n\n# Keyboard shortcuts\nCtrl+Y - Toggle YOLO mode (auto-approve all operations - use with caution!)\n\n# Direct input of task descriptions to execute agent\n```\n\n### YOLO Mode\n\n**Use with caution:**\n- Press `Ctrl+Y` to toggle YOLO mode\n- **Default behavior**: All tool calls require user confirmation for safety\n- In YOLO mode, all tool calls are automatically approved without user confirmation\n- This speeds up execution but removes safety checks\n- Mode status is displayed in the interface\n- You can also type 'a' (always) when prompted for tool confirmation to enable YOLO mode\n\n### Configuration Management\n\nPywen uses the `pywen_config.json` file for configuration:\n\n```json\n{\n \"default_provider\": \"qwen\",\n \"max_steps\": 20,\n \"enable_lakeview\": false,\n \"model_providers\": {\n \"qwen\": {\n \"api_key\": \"your-qwen-api-key\",\n \"base_url\": \"https://dashscope.aliyuncs.com/compatible-mode/v1\",\n \"model\": \"qwen3-coder-plus\",\n \"max_tokens\": 4096,\n \"temperature\": 0.5\n }\n }\n}\n```\n\n**Configuration Priority:**\n1. Command line arguments (highest)\n2. Configuration file values\n3. Environment variables\n4. Default values (lowest)\n\n### Environment Variables\n\nYou can set API keys through environment variables:\n\n```bash\n# Qwen (required)\nexport QWEN_API_KEY=\"your-qwen-api-key\"\n\n# Tool API Keys (optional but recommended)\nexport SERPER_API_KEY=\"your-serper-api-key\" # For web search\nexport JINA_API_KEY=\"your-jina-api-key\" # For content reading\n\n# Other supported providers\nexport OPENAI_API_KEY=\"your-openai-api-key\"\nexport ANTHROPIC_API_KEY=\"your-anthropic-api-key\"\n```\n\n### Getting API Keys\n\n**Serper API (Web Search):**\n1. Visit [serper.dev](https://serper.dev/)\n2. Sign up for a free account\n3. Get your API key from the dashboard\n\n**Jina API (Content Reading):**\n1. Visit [jina.ai](https://jina.ai/)\n2. Sign up for a free account\n3. Get your API key from the dashboard\n\n## \ud83d\udee0\ufe0f Available Tools\n\nPywen provides a comprehensive toolkit for software development:\n\n- **File Operations**: Create, edit, read, and manage files\n- **Bash Execution**: Run shell commands and scripts\n- **Sequential Thinking**: Structured problem-solving approach\n- **Task Completion**: Mark tasks as complete with summaries\n- **JSON Operations**: Parse and manipulate JSON data\n\nFor detailed information about all available tools and their capabilities, see [docs/tools.md](docs/tools.md).\n\n## \ud83d\udcca Trajectory Recording\n\nPywen automatically records detailed execution trajectories for debugging and analysis:\n\n```bash\n# Trajectory files are automatically saved to trajectories/ directory\ntrajectories/trajectory_xxxxxx.json\n```\n\nTrajectory files contain:\n- **LLM Interactions**: All messages, responses, and tool calls\n- **Agent Steps**: State transitions and decision points\n- **Tool Usage**: Which tools were called and their results\n- **Metadata**: Timestamps, token usage, and execution metrics\n\n## \ud83d\udcc8 Session Statistics\n\nMonitor your usage with real-time statistics:\n\n```bash\n> /stats\n```\n\nTracks:\n- API calls and token consumption\n- Tool usage patterns\n- Session duration\n- Model performance metrics\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions to Pywen! Here's how to get started:\n\n1. Fork the repository\n2. Set up the development environment:\n ```bash\n git clone https://github.com/your-username/Pywen.git\n cd Pywen\n uv venv\n uv sync --all-extras\n\n # linux/macos\n source .venv/bin/activate\n\n # windows\n .venv\\Scripts\\activate\n ```\n3. Create a feature branch\n4. Make your changes and add tests\n5. Submit a pull request\n\n### Development Guidelines\n\n- Follow PEP 8 style guidelines\n- Add tests for new features\n- Update documentation as needed\n- Use type hints appropriately\n- Ensure all tests pass before submitting\n\n## \ud83d\udccb Requirements\n\n- Python 3.12+\n- Qwen API key (recommended) or other supported LLM provider API keys\n- Internet connection for API access\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues\n\n**Configuration Issues:**\n```bash\n# Re-run configuration wizard\nrm pywen_config.json\npywen\n```\n\n**API Key Issues:**\n```bash\n# Verify your API key is set\necho $QWEN_API_KEY\n\n# Check configuration in Pywen\n> /config\n```\n\n## \ud83d\ude4f Acknowledgments\n\nWe thank:\n\n- **Google** for the [Gemini CLI](https://github.com/google-gemini/gemini-cli) project, which provided agent execution logic and rich tool ecosystem libraries for this project\n- **Alibaba Cloud Qwen Team** for providing the powerful [Qwen3-Coder](https://github.com/QwenLM/Qwen3-Coder) model and [Qwen-Code](https://github.com/QwenLM/qwen-code) reference implementation\n- **ByteDance** for the [trae-agent](https://github.com/bytedance/trae-agent) project, which provided valuable foundational architecture for this project\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Pywen - Making the power of Qwen3-Coder accessible for intelligent software development!** \ud83d\ude80\n\n**PAMPAS-Lab - Dedicated to breakthroughs in large model agent frameworks, bridging AI research and applications!** \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "LLM-based agent for general purpose tasks",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"agent",
" cli",
" llm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "39adf02552d2c9bfeaa49837976a66c6649a17b2371c6f1dc42f765bec28b8f5",
"md5": "14e160c2f668430f0dfe797bc31ad694",
"sha256": "ee8f4c8812cd12ee55672f23b35ed81a2c52d7919d81c838d3d784b20f7a0bc3"
},
"downloads": -1,
"filename": "pywen_agent-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14e160c2f668430f0dfe797bc31ad694",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 252323,
"upload_time": "2025-08-05T06:28:48",
"upload_time_iso_8601": "2025-08-05T06:28:48.110789Z",
"url": "https://files.pythonhosted.org/packages/39/ad/f02552d2c9bfeaa49837976a66c6649a17b2371c6f1dc42f765bec28b8f5/pywen_agent-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "230772b4e146c3aa0adc8b0af2e46574a2f8e0e2a4b4c8fec07c915687010719",
"md5": "d84b63e7132cdf5a302c775e20eb384f",
"sha256": "ac1dceeff3f1ab374f551893d20bc02ea8de223ec58de586a7ea10d2deb6bbfb"
},
"downloads": -1,
"filename": "pywen_agent-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d84b63e7132cdf5a302c775e20eb384f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 212258,
"upload_time": "2025-08-05T06:28:49",
"upload_time_iso_8601": "2025-08-05T06:28:49.529484Z",
"url": "https://files.pythonhosted.org/packages/23/07/72b4e146c3aa0adc8b0af2e46574a2f8e0e2a4b4c8fec07c915687010719/pywen_agent-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 06:28:49",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pywen-agent"
}
