Skip to content

Commit a77acc9

Browse files
unseriousAIclaude
unseriousAI
and
claude
committed
Simplify README and remove redundant sections
Remove stale changelog entries, consolidate duplicate loadout documentation into a single table, merge helper/loader sections, and convert verbose feature descriptions to compact formats. Cuts README from 326 to 173 lines with no information loss. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 713caab commit a77acc9

1 file changed

Lines changed: 88 additions & 225 deletions

File tree

‎README.md‎

Lines changed: 88 additions & 225 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,6 @@
22

33
An open foundational toolkit providing essential components for building AI agents with minimal dependencies for local (non-HTTP/API) actions.
44

5-
## 🆕 What's New in v1.3.0
6-
7-
🎯 **NEW: Loadouts** - 6 pre-configured tool bundles for specific use cases (coder, docs writer, data analyst, web publisher, visual designer, office suite)
8-
9-
📝 **Markdown Enhancements**: Advanced HTML conversion with blockquotes, tables, task lists, and 5 new parsing functions
10-
11-
📅 **DateTime Improvements**: 6 new formatting/parsing functions for human-readable dates, times, and durations
12-
13-
### Recent Updates
14-
15-
**v1.2.0** - Markdown and datetime enhancements, datetime essentials helper
16-
17-
**v1.1.0** - New helper functions: Added 10 use-case focused tool loaders for targeted agent capabilities
18-
19-
**v0.13.6** - Enhanced confirmation dialogs with content previews for better decision-making
20-
21-
**v0.13.3** - Added structured logging with `BOAT_LOG_LEVEL` environment variable control
22-
23-
**v0.13.2** - Smart confirmation system that adapts to interactive, agent, or automation contexts
24-
255
## Installation
266

277
```bash
@@ -36,66 +16,49 @@ uv add basic-open-agent-tools
3616
### Optional Dependencies
3717

3818
```bash
39-
# All features
40-
pip install basic-open-agent-tools[all]
41-
42-
# Specific features
43-
pip install basic-open-agent-tools[system] # Process management, system info
44-
pip install basic-open-agent-tools[pdf] # PDF reading and creation
45-
pip install basic-open-agent-tools[xml] # XML parsing and validation
46-
pip install basic-open-agent-tools[word] # Word document operations
47-
pip install basic-open-agent-tools[excel] # Excel spreadsheet operations
48-
pip install basic-open-agent-tools[powerpoint] # PowerPoint presentations
49-
pip install basic-open-agent-tools[image] # Image processing
19+
pip install basic-open-agent-tools[all] # Everything
20+
pip install basic-open-agent-tools[system] # Process management, system info
21+
pip install basic-open-agent-tools[pdf] # PDF reading and creation
22+
pip install basic-open-agent-tools[xml] # XML parsing and validation
23+
pip install basic-open-agent-tools[word] # Word document operations
24+
pip install basic-open-agent-tools[excel] # Excel spreadsheet operations
25+
pip install basic-open-agent-tools[powerpoint] # PowerPoint presentations
26+
pip install basic-open-agent-tools[image] # Image processing
27+
pip install basic-open-agent-tools[data] # YAML and TOML support
5028
```
5129

5230
## Quick Start
5331

5432
```python
5533
import basic_open_agent_tools as boat
5634

57-
# Option 1: Load all tools (337 functions)
58-
all_tools = boat.load_all_tools()
35+
# Essential tools for general-purpose agents (~23 tools)
36+
tools = boat.load_essential()
5937

60-
# Option 2: Use pre-configured loadouts for specific use cases
61-
coder_tools = boat.load_coder_loadout() # ~105 tools for development
62-
docs_tools = boat.load_docs_loadout() # ~130 tools for documentation
63-
analyst_tools = boat.load_data_analyst_loadout() # ~115 tools for data analysis
64-
web_tools = boat.load_web_publisher_loadout() # ~90 tools for web content
65-
designer_tools = boat.load_visual_designer_loadout() # ~60 tools for graphics
66-
office_tools = boat.load_office_suite_loadout() # ~80 tools for Office work
38+
# Pre-configured loadouts for specific roles
39+
tools = boat.load_coder_loadout() # ~105 tools for development
40+
tools = boat.load_docs_loadout() # ~130 tools for documentation
41+
tools = boat.load_data_analyst_loadout() # ~115 tools for data analysis
42+
tools = boat.load_web_publisher_loadout() # ~90 tools for web content
43+
tools = boat.load_visual_designer_loadout() # ~60 tools for graphics
44+
tools = boat.load_office_suite_loadout() # ~80 tools for Office work
6745

68-
# Option 3: Load specific categories
69-
fs_tools = boat.load_all_filesystem_tools()
70-
text_tools = boat.load_all_text_tools()
71-
data_tools = boat.load_all_data_tools()
72-
73-
# Merge selected categories
74-
custom_tools = boat.merge_tool_lists(fs_tools, text_tools, data_tools)
46+
# Or load everything
47+
tools = boat.load_all_tools() # All 337 functions
7548

7649
# Use with any agent framework
7750
from google.adk.agents import Agent
78-
79-
# General-purpose agent
80-
agent = Agent(tools=all_tools)
81-
82-
# Specialized developer agent
83-
dev_agent = Agent(tools=boat.load_coder_loadout())
84-
85-
# Documentation writer agent
86-
docs_agent = Agent(tools=boat.load_docs_loadout())
51+
agent = Agent(tools=boat.load_coder_loadout())
8752
```
8853

8954
## Available Modules
9055

9156
**21 modules** with **337 total functions** — all with `@strands_tool` decorator and Google ADK compatible signatures.
9257

93-
### 📊 Complete Module Breakdown
94-
95-
| Module | Functions | Description |
96-
|--------|-----------|-------------|
58+
| Module | Count | Description |
59+
|--------|------:|-------------|
9760
| **Core Operations** | | |
98-
| `file_system` | 19 | File and directory operations, tree generation |
61+
| `file_system` | 19 | File/directory operations, tree generation |
9962
| `text` | 10 | Text processing, case conversion, formatting |
10063
| `data` | 23 | JSON, CSV, YAML, TOML processing and validation |
10164
| `datetime` | 46 | Date/time operations, timezones, formatting, parsing |
@@ -120,206 +83,106 @@ docs_agent = Agent(tools=boat.load_docs_loadout())
12083
| **Task Management** | | |
12184
| `todo` | 8 | Task creation, validation, management |
12285
| `logging` | 5 | Structured logging and log rotation |
123-
| **TOTAL** | **337** | |
12486

12587
## Key Features
12688

127-
✨ **Agent-Friendly**: Simplified type signatures prevent "signature too complex" errors
128-
129-
🚀 **Minimal Dependencies**: Pure Python core with optional dependencies only when needed
89+
- **Agent-Friendly** — Simplified type signatures prevent "signature too complex" errors
90+
- **Minimal Dependencies** — Pure Python core; optional deps only when needed
91+
- **Modular** — Load only what you need
92+
- **Multi-Framework** — Works with Google ADK, LangChain, Strands Agents, custom frameworks
93+
- **Smart Confirmations** — Write/delete operations adapt to interactive, agent, or automation contexts
94+
- **Pre-configured Loadouts** — 6 curated tool bundles optimized for specific use cases
13095

131-
🔧 **Modular**: Load only what you need
132-
133-
🤝 **Multi-Framework**: Works with Google ADK (signature-based), LangChain, Strands Agents (@strands_tool decorator), custom frameworks
134-
135-
🔍 **Enhanced Feedback**: Detailed operation confirmations with `skip_confirm` safety parameter
136-
137-
🎯 **Pre-configured Loadouts**: 6 curated tool bundles optimized for specific use cases with minimal overlap
138-
139-
## Loadouts - Pre-configured Tool Bundles
96+
## Loadouts
14097

14198
Choose the right loadout for your agent's role to minimize token usage and maximize relevance:
14299

143-
### 1. `load_coder_loadout()` (~105 tools)
144-
**For**: Software developers, DevOps engineers, automation scripts
145-
146-
**Includes**: File system, system operations, network, logging, crypto, archive, config files (YAML, TOML, JSON, INI)
147-
148-
**Example Agents**:
149-
- DevOps agent managing deployments and server configs
150-
- Project setup agent scaffolding new projects
151-
152-
### 2. `load_docs_loadout()` (~130 tools)
153-
**For**: Technical writers, documentation creators, report generators
154-
155-
**Includes**: Word, PDF, Markdown, HTML, diagrams, images, text processing
100+
| Loadout | Tools | Best For | Includes |
101+
|---------|------:|----------|----------|
102+
| `load_coder_loadout()` | ~105 | Dev, DevOps, automation | File system, system ops, network, logging, crypto, archive, configs |
103+
| `load_docs_loadout()` | ~130 | Technical writing, reports | Word, PDF, Markdown, HTML, diagrams, images, text |
104+
| `load_data_analyst_loadout()` | ~115 | Data/financial analysis, BI | Excel, CSV, validation, diagrams, JSON, YAML, XML |
105+
| `load_web_publisher_loadout()` | ~90 | Web dev, content management | HTML, XML, Markdown, network, text processing |
106+
| `load_visual_designer_loadout()` | ~60 | Graphics, infographics | Image processing, diagrams, color tools |
107+
| `load_office_suite_loadout()` | ~80 | Office productivity | Excel, Word, PowerPoint, file operations |
156108

157-
**Example Agents**:
158-
- Technical writer creating API documentation
159-
- Report generator compiling findings into formatted documents
109+
## Tool Loaders
160110

161-
### 3. `load_data_analyst_loadout()` (~115 tools)
162-
**For**: Data analysts, financial analysts, business intelligence
111+
Beyond loadouts, build custom tool sets by combining loaders:
163112

164-
**Includes**: Excel, CSV, data validation, diagrams, structured data formats (JSON, YAML, XML)
165-
166-
**Example Agents**:
167-
- Financial analyst processing budgets and creating reports
168-
- BI agent generating dashboards and analytics
169-
170-
### 4. `load_web_publisher_loadout()` (~90 tools)
171-
**For**: Web developers, content managers, blog publishers
172-
173-
**Includes**: HTML, XML, Markdown, network operations, text processing
174-
175-
**Example Agents**:
176-
- Blog publisher converting drafts to HTML
177-
- Documentation site generator creating static websites
178-
179-
### 5. `load_visual_designer_loadout()` (~60 tools)
180-
**For**: Graphic designers, infographic creators, visual content producers
181-
182-
**Includes**: Image processing, diagrams, color tools, file operations
113+
```python
114+
import basic_open_agent_tools as boat
183115

184-
**Example Agents**:
185-
- Infographic generator creating data visualizations
186-
- Brand asset manager processing images and color palettes
116+
# Use-case focused loaders
117+
boat.load_essential() # ~23 most commonly needed tools
118+
boat.load_core_readonly() # 28 read-only tools (filesystem, text, data parsing)
119+
boat.load_converters() # 78 pure transformation tools (text, datetime, crypto, color)
120+
boat.load_document_readers() # Extract content from PDF, Word, Excel, PowerPoint, images
121+
boat.load_writers() # All file creation/modification tools
122+
boat.load_analyst_tools() # Data analysis and validation tools
123+
boat.load_web_tools() # HTML, Markdown, network operations
124+
boat.load_devtools() # Debugging, logging, performance measurement
125+
boat.load_structured_data_tools() # CSV, JSON, XML, YAML, TOML, INI
126+
boat.load_office_suite() # Excel, Word, PowerPoint tools
127+
boat.load_markup_tools() # HTML, Markdown, XML processing
187128

188-
### 6. `load_office_suite_loadout()` (~80 tools)
189-
**For**: Office workers, business users, administrative assistants
129+
# Per-module loaders (21 total — one for each module)
130+
boat.load_all_filesystem_tools()
131+
boat.load_all_text_tools()
132+
boat.load_all_data_tools()
133+
# ... etc.
190134

191-
**Includes**: Excel, Word, PowerPoint, file operations, datetime essentials
135+
# Combine and deduplicate
136+
custom = boat.merge_tool_lists(
137+
boat.load_all_filesystem_tools(),
138+
boat.load_all_text_tools(),
139+
boat.load_all_data_tools(),
140+
)
192141

193-
**Example Agents**:
194-
- Office assistant creating business reports and presentations
195-
- Administrative agent managing documents and schedules
142+
# Inspect available tools
143+
boat.list_all_available_tools() # List all tool names
144+
boat.get_tool_info(some_tool) # Get tool metadata
145+
```
196146

197147
## Safety Features
198148

199-
### Smart Confirmation System (3 Modes)
200-
201-
All write/delete operations include a `skip_confirm` parameter with intelligent confirmation handling:
149+
All write/delete operations include a `skip_confirm` parameter with three modes:
202150

203-
**🔄 Bypass Mode** - `skip_confirm=True` or `BYPASS_TOOL_CONSENT=true` env var
204-
- Proceeds immediately without prompts
205-
- Perfect for CI/CD and automation
206-
207-
**💬 Interactive Mode** - Terminal with `skip_confirm=False`
208-
- Prompts user with `y/n` confirmation
209-
- Shows preview info (file sizes, etc.)
210-
211-
**🤖 Agent Mode** - Non-TTY with `skip_confirm=False`
212-
- Raises `CONFIRMATION_REQUIRED` error with instructions
213-
- LLM agents can ask user and retry with `skip_confirm=True`
151+
| Mode | When | Behavior |
152+
|------|------|----------|
153+
| **Bypass** | `skip_confirm=True` or `BYPASS_TOOL_CONSENT=true` env var | Proceeds immediately — for CI/CD and automation |
154+
| **Interactive** | Terminal with `skip_confirm=False` | Prompts user with `y/n` and preview info |
155+
| **Agent** | Non-TTY with `skip_confirm=False` | Raises `CONFIRMATION_REQUIRED` error; LLM can ask user and retry |
214156

215157
```python
216-
# Safe by default - adapts to context
217-
result = boat.file_system.write_file_from_string(
158+
# Safe by default — adapts to context
159+
boat.file_system.write_file_from_string(
218160
file_path="/tmp/example.txt",
219161
content="Hello, World!",
220162
skip_confirm=False # Interactive prompt OR agent error
221163
)
222164

223-
# Explicit overwrite
224-
result = boat.file_system.write_file_from_string(
165+
# Explicit bypass
166+
boat.file_system.write_file_from_string(
225167
file_path="/tmp/example.txt",
226168
content="Updated content",
227-
skip_confirm=True # Bypasses all confirmations
169+
skip_confirm=True
228170
)
229-
230-
# Automation mode
231-
import os
232-
os.environ['BYPASS_TOOL_CONSENT'] = 'true'
233-
# All confirmations bypassed for CI/CD
234171
```
235172

236173
## Documentation
237174

238-
- **[Getting Started](docs/getting-started.md)** - Installation and setup
239-
- **[API Reference](docs/api-reference.md)** - Complete function reference
240-
- **[Examples](docs/examples.md)** - Usage examples and patterns
241-
- **[FAQ](docs/faq.md)** - Troubleshooting and common questions
242-
- **[Contributing](docs/contributing.md)** - Development guidelines
243-
- **[Changelog](CHANGELOG.md)** - Version history
244-
245-
## Helper Functions
246-
247-
### Rapid Loaders - Pre-configured Loadouts (6 total)
248-
249-
Optimized tool bundles for specific roles and use cases - minimal overlap, maximum relevance:
250-
251-
```python
252-
import basic_open_agent_tools as boat
253-
254-
# Loadouts - Choose the one that matches your agent's role
255-
boat.load_coder_loadout() # ~105 tools - Development, DevOps, automation
256-
boat.load_docs_loadout() # ~130 tools - Document creation (Word, PDF, Markdown, HTML)
257-
boat.load_data_analyst_loadout() # ~115 tools - Data analysis (Excel, CSV, validation)
258-
boat.load_web_publisher_loadout() # ~90 tools - Web content (HTML, XML, Markdown)
259-
boat.load_visual_designer_loadout() # ~60 tools - Graphics (Images, Diagrams, Color)
260-
boat.load_office_suite_loadout() # ~80 tools - Office productivity (Excel, Word, PowerPoint)
261-
```
262-
263-
### Generic Loaders
264-
265-
Build custom tool sets by combining modules:
266-
267-
```python
268-
# Master loader
269-
boat.load_all_tools() # Load all 337 functions
270-
271-
# Category loaders (21 total)
272-
boat.load_all_filesystem_tools()
273-
boat.load_all_text_tools()
274-
boat.load_all_data_tools()
275-
boat.load_all_datetime_tools()
276-
boat.load_all_excel_tools()
277-
boat.load_all_xml_tools()
278-
boat.load_all_pdf_tools()
279-
boat.load_all_word_tools()
280-
boat.load_all_html_tools()
281-
boat.load_all_markdown_tools()
282-
boat.load_all_powerpoint_tools()
283-
boat.load_all_diagrams_tools()
284-
boat.load_all_system_tools()
285-
boat.load_all_network_tools()
286-
boat.load_all_utilities_tools()
287-
boat.load_all_crypto_tools()
288-
boat.load_all_color_tools()
289-
boat.load_all_image_tools()
290-
boat.load_all_archive_tools()
291-
boat.load_all_todo_tools()
292-
boat.load_all_logging_tools()
293-
294-
# Specialized data loaders (4 total)
295-
boat.load_data_json_tools() # JSON operations
296-
boat.load_data_csv_tools() # CSV operations
297-
boat.load_data_validation_tools() # Data validation
298-
boat.load_data_config_tools() # YAML, TOML, INI
299-
300-
# Use-case focused loaders (10 total)
301-
boat.load_essential() # ~25 most commonly needed tools
302-
boat.load_core_readonly() # 28 read-only tools (filesystem, text, data parsing)
303-
boat.load_converters() # 78 pure transformation tools (text, datetime, crypto, color)
304-
boat.load_document_readers() # Extract content from PDF, Word, Excel, PowerPoint, images
305-
boat.load_writers() # All file creation/modification tools
306-
boat.load_analyst_tools() # Data analysis and validation tools
307-
boat.load_web_tools() # HTML, Markdown, network operations
308-
boat.load_devtools() # Debugging, logging, performance measurement
309-
boat.load_structured_data_tools() # CSV, JSON, XML, YAML, TOML, INI
310-
boat.load_office_suite() # Excel, Word, PowerPoint tools
311-
boat.load_markup_tools() # HTML, Markdown, XML processing
312-
313-
# Utility functions
314-
boat.merge_tool_lists(*tool_lists) # Merge and deduplicate
315-
boat.list_all_available_tools() # List all tool names
316-
boat.get_tool_info(tool_name) # Get tool metadata
317-
```
175+
- **[Getting Started](docs/getting-started.md)** — Installation and setup
176+
- **[API Reference](docs/api-reference.md)** — Complete function reference
177+
- **[Examples](docs/examples.md)** — Usage examples and patterns
178+
- **[FAQ](docs/faq.md)** — Troubleshooting and common questions
179+
- **[Contributing](docs/contributing.md)** — Development guidelines
180+
- **[Changelog](CHANGELOG.md)** — Version history
318181

319182
## Contributing
320183

321184
We welcome contributions! See our [Contributing Guide](docs/contributing.md) for development setup, coding standards, and pull request process.
322185

323186
## License
324187

325-
MIT License - see [LICENSE](LICENSE) for details.
188+
MIT License — see [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)