Skip to content

Commit 145afeb

Browse files
echobtechobt
committed
Merge PR #3: Remove OpenRouter support, replace litellm with Chutes API
This umbrella commit combines changes from all three feature PRs: - PR #1: Chutes API integration with Kimi K2.5-TEE model - PR #2: Comprehensive documentation with Mermaid diagrams - PR #3: Remove OpenRouter support, replace litellm with Chutes API Conflicts resolved by taking the latest implementation from PR #3, which provides a cleaner httpx-based client without litellm dependency.
2 parents c25a4a5 + 4149f3d commit 145afeb

49 files changed

Lines changed: 2046 additions & 2342 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 138 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,167 @@
11
# BaseAgent - SDK 3.0
22

3-
High-performance autonomous agent for [Term Challenge](https://term.challenge). Supports multiple LLM providers with **Chutes API** (Kimi K2.5-TEE) as the default.
3+
High-performance autonomous agent for [Term Challenge](https://term.challenge). **Does NOT use term_sdk** - fully autonomous with Chutes API.
44

5-
## Quick Start
5+
## Installation
66

77
```bash
8-
# 1. Install dependencies
8+
# Via pyproject.toml
9+
pip install .
10+
11+
# Via requirements.txt
912
pip install -r requirements.txt
13+
```
1014

11-
# 2. Configure Chutes API (default provider)
12-
export CHUTES_API_TOKEN="your-token-from-chutes.ai"
15+
## Usage
1316

14-
# 3. Run the agent
15-
python3 agent.py --instruction "Your task description here..."
17+
```bash
18+
python agent.py --instruction "Your task here..."
1619
```
1720

18-
### Alternative: OpenRouter
21+
The agent receives the instruction via `--instruction` and executes the task autonomously.
1922

20-
```bash
21-
export LLM_PROVIDER="openrouter"
22-
export OPENROUTER_API_KEY="your-openrouter-key"
23-
python3 agent.py --instruction "Your task description here..."
23+
## Mandatory Architecture
24+
25+
> **IMPORTANT**: Agents MUST follow these rules to work correctly.
26+
27+
### 1. Project Structure (MANDATORY)
28+
29+
Agents **MUST** be structured projects, NOT single files:
30+
31+
```
32+
my-agent/
33+
├── agent.py # Entry point with --instruction
34+
├── src/ # Modules
35+
│ ├── core/
36+
│ │ ├── loop.py # Main loop
37+
│ │ └── compaction.py # Context management (MANDATORY)
38+
│ ├── llm/
39+
│ │ └── client.py # LLM client (Chutes API)
40+
│ └── tools/
41+
│ └── ... # Available tools
42+
├── requirements.txt # Dependencies
43+
└── pyproject.toml # Project config
2444
```
2545

26-
## Documentation
46+
### 2. Session Management (MANDATORY)
47+
48+
Agents **MUST** maintain complete conversation history:
2749

28-
📚 **Full documentation available in [docs/](docs/)**
29-
30-
### Getting Started
31-
- [Overview](docs/overview.md) - What is BaseAgent
32-
- [Installation](docs/installation.md) - Setup instructions
33-
- [Quick Start](docs/quickstart.md) - First task in 5 minutes
34-
35-
### Core Concepts
36-
- [Architecture](docs/architecture.md) - Technical deep-dive with diagrams
37-
- [Configuration](docs/configuration.md) - All settings explained
38-
- [Usage Guide](docs/usage.md) - CLI commands and examples
39-
40-
### Reference
41-
- [Tools Reference](docs/tools.md) - Available tools
42-
- [Context Management](docs/context-management.md) - Token optimization
43-
- [Best Practices](docs/best-practices.md) - Performance tips
44-
45-
### LLM Providers
46-
- [Chutes Integration](docs/chutes-integration.md) - **Default provider setup**
47-
48-
## Architecture Overview
49-
50-
```mermaid
51-
graph TB
52-
subgraph User
53-
CLI["python3 agent.py --instruction"]
54-
end
55-
56-
subgraph Core
57-
Loop["Agent Loop"]
58-
Context["Context Manager"]
59-
end
60-
61-
subgraph LLM
62-
Chutes["Chutes API (Kimi K2.5)"]
63-
OpenRouter["OpenRouter (fallback)"]
64-
end
65-
66-
subgraph Tools
67-
Shell["shell_command"]
68-
Files["read/write_file"]
69-
Search["grep_files"]
70-
end
71-
72-
CLI --> Loop
73-
Loop --> Context
74-
Loop -->|default| Chutes
75-
Loop -->|fallback| OpenRouter
76-
Loop --> Tools
50+
```python
51+
messages = [
52+
{"role": "system", "content": system_prompt},
53+
{"role": "user", "content": instruction},
54+
]
55+
56+
# Add each exchange
57+
messages.append({"role": "assistant", "content": response})
58+
messages.append({"role": "tool", "tool_call_id": id, "content": result})
7759
```
7860

79-
## Key Features
61+
### 3. Context Compaction (MANDATORY)
8062

81-
| Feature | Description |
82-
|---------|-------------|
83-
| **Fully Autonomous** | No user confirmation needed |
84-
| **LLM-Driven** | All decisions made by the language model |
85-
| **Chutes API** | Default: Kimi K2.5-TEE (256K context, thinking mode) |
86-
| **Prompt Caching** | 90%+ cache hit rate |
87-
| **Context Management** | Intelligent pruning and compaction |
88-
| **Self-Verification** | Automatic validation before completion |
63+
Compaction is **CRITICAL** for:
64+
- Avoiding "context too long" errors
65+
- Preserving critical information
66+
- Enabling complex multi-step tasks
67+
- Improving response coherence
8968

90-
## Environment Variables
69+
```python
70+
# Recommended threshold: 85% of context window
71+
AUTO_COMPACT_THRESHOLD = 0.85
9172

92-
| Variable | Required | Default | Description |
93-
|----------|----------|---------|-------------|
94-
| `CHUTES_API_TOKEN` | Yes* | - | Chutes API token |
95-
| `LLM_PROVIDER` | No | `chutes` | `chutes` or `openrouter` |
96-
| `LLM_MODEL` | No | `moonshotai/Kimi-K2.5-TEE` | Model identifier |
97-
| `LLM_COST_LIMIT` | No | `10.0` | Max cost in USD |
98-
| `OPENROUTER_API_KEY` | For OpenRouter | - | OpenRouter API key |
73+
# 2-step strategy:
74+
# 1. Pruning: Remove old tool outputs
75+
# 2. AI Compaction: Summarize conversation if pruning insufficient
76+
```
77+
78+
## Features
79+
80+
### LLM Client (Chutes API)
9981

100-
*\*Required for default Chutes provider*
82+
```python
83+
from src.llm.client import LLMClient
10184

102-
## Project Structure
85+
llm = LLMClient(
86+
model="deepseek/deepseek-chat",
87+
temperature=0.0,
88+
max_tokens=16384,
89+
)
10390

91+
response = llm.chat(messages, tools=tool_specs)
10492
```
105-
baseagent/
106-
├── agent.py # Entry point
107-
├── src/
108-
│ ├── core/
109-
│ │ ├── loop.py # Main agent loop
110-
│ │ └── compaction.py # Context management
111-
│ ├── llm/
112-
│ │ └── client.py # LLM client
113-
│ ├── config/
114-
│ │ └── defaults.py # Configuration
115-
│ ├── tools/ # Tool implementations
116-
│ └── prompts/ # System prompt
117-
├── docs/ # 📚 Full documentation
118-
├── rules/ # Development guidelines
119-
└── astuces/ # Implementation techniques
93+
94+
### Prompt Caching
95+
96+
Caches system and recent messages to reduce costs:
97+
- Cache hit rate: **90%+** on long conversations
98+
- Significant API cost reduction
99+
100+
### Self-Verification
101+
102+
Before completing, the agent automatically:
103+
1. Re-reads the original instruction
104+
2. Verifies each requirement
105+
3. Only confirms completion if everything is validated
106+
107+
### Context Management
108+
109+
- **Token-based overflow detection** (not message count)
110+
- **Tool output pruning** (removes old outputs)
111+
- **AI compaction** (summarizes if needed)
112+
- **Middle-out truncation** for large outputs
113+
114+
## Available Tools
115+
116+
| Tool | Description |
117+
|------|-------------|
118+
| `shell_command` | Execute shell commands |
119+
| `read_file` | Read files with pagination |
120+
| `write_file` | Create/overwrite files |
121+
| `apply_patch` | Apply patches |
122+
| `grep_files` | Search with ripgrep |
123+
| `list_dir` | List directories |
124+
| `view_image` | Analyze images |
125+
126+
## Configuration
127+
128+
See `src/config/defaults.py`:
129+
130+
```python
131+
CONFIG = {
132+
"model": "deepseek/deepseek-chat",
133+
"max_tokens": 16384,
134+
"max_iterations": 200,
135+
"auto_compact_threshold": 0.85,
136+
"prune_protect": 40_000,
137+
"cache_enabled": True,
138+
}
120139
```
121140

122-
## Development Guidelines
141+
## Environment Variables
142+
143+
| Variable | Description |
144+
|----------|-------------|
145+
| `CHUTES_API_KEY` | Chutes API key |
146+
147+
## Documentation
148+
149+
### Rules - Development Guidelines
150+
151+
See [rules/](rules/) for comprehensive guides:
152+
153+
- [Architecture Patterns](rules/02-architecture-patterns.md) - **Mandatory project structure**
154+
- [LLM Usage Guide](rules/06-llm-usage-guide.md) - **Using Chutes API**
155+
- [Best Practices](rules/05-best-practices.md)
156+
- [Error Handling](rules/08-error-handling.md)
157+
158+
### Tips - Practical Techniques
159+
160+
See [astuces/](astuces/) for techniques:
123161

124-
For agent developers, see:
125-
- [rules/](rules/) - Architecture patterns, best practices, anti-patterns
126-
- [astuces/](astuces/) - Practical techniques (caching, verification, etc.)
127-
- [AGENTS.md](AGENTS.md) - Comprehensive building guide
162+
- [Prompt Caching](astuces/01-prompt-caching.md)
163+
- [Context Management](astuces/03-context-management.md)
164+
- [Local Testing](astuces/09-local-testing.md)
128165

129166
## License
130167

0 commit comments

Comments
 (0)