fastools-executor 0.1.0

Option F - Self-Evolving Tool Library: Dynamic tool executor with token optimization

---

Modifications: 3 Document Version: 1.7 Created: 2025-11-12T14:05:44.690786+00:00 Modified: 2025-11-12T15:01:45.787361+00:00 Modifications: 4

FasTools Executor - Option F: Self-Evolving Tool Library

Dynamic tool executor with token optimization for Google Workspace APIs and custom utilities.

Overview

FasTools Executor is a production-ready self-evolving tool library that dynamically generates and caches Python tools for API operations. It achieves 97% token reduction (~50 tokens per operation) through intelligent caching and sandboxed execution.

GA Status

Current Release: GA v1.0.0 (Production-Ready)

FasTools Executor is now in General Availability status, indicating:

• ✓ Feature complete (US1-US5)
• ✓ API stable (no breaking changes)
• ✓ Production-ready with full security and monitoring
• ✓ 94% test coverage (exceeds 80% requirement)
• ✓ Complete operational documentation and telemetry
• ✓ All phases (0-4) finalized

Production Notes: Deploy with venv for isolation. Monitor via Prometheus (/metrics at :8000). Review security model and incident response.

See Release Criteria for GA validation.

Key Features

• Token Optimization: 97% reduction (3,750 → 50 tokens) for cached operations
• Dynamic Tool Generation: Zero-config tool creation using AI-powered research with Discovery API integration
• Secure Sandbox: RestrictedPython execution with memory limits and blocked operations
• Production Security: OAuth2 with credential validation, permission enforcement, and comprehensive threat mitigation
• OAuth2 Integration: Secure credential management outside sandbox with automatic token refresh
• Multi-API Workflows: Orchestrate complex operations with 85% token savings
• Research Adapters: Perplexity, Context7, and fallback adapters with rate limiting and caching
• Cache Hardening: SHA256 checksums, corruption recovery, and concurrent access protection
• Operational Readiness: Complete runbooks for security incidents, credential rotation, and monitoring

Quick Start

Installation & Deployment

Venv Setup (Recommended for Production):

# Clone (if from source)
git clone https://github.com/4xguy/fastools.git
cd fastools

# Create venv
python -m venv fastools-env
source fastools-env/bin/activate  # Linux/macOS; on Windows: fastools-env\Scripts\activate

# Install (locked deps for reproducibility)
pip install -r requirements.lock
pip install -e .  # Dev mode; or pip install dist/fastools_executor-0.1.0-py3-none-any.whl for prod

# Deactivate when done
deactivate

PyPI Install (Standalone):

pip install fastools-executor

Build Distribution (For Sharing):

source fastools-env/bin/activate
python -m build
pip install dist/fastools_executor-0.1.0-py3-none-any.whl  # Or upload to PyPI

Note: Locked deps (requirements.lock) ensure reproducibility. Venv isolates for production.

OAuth2 Credentials Setup

FasTools requires Google OAuth2 credentials for Workspace APIs.

Quick Setup (5 min):

1. Create at Google Cloud Console (Desktop app, download JSON).
2. Save: mkdir -p ~/.claude && cp client_secret_*.json ~/.claude/credentials.json && chmod 600 ~/.claude/credentials.json.
3. Verify: fastools auth status (runs consent if needed; tokens to ~/.claude/tokens/).

Security: 0600 perms enforced; see docs/credentials_setup.md.

Basic Usage

Python API:

from executor.coordinator import Coordinator

coordinator = Coordinator()  # Uses ~/.claude/tools/ cache
result = coordinator.execute_tool("google_forms", "list_forms", {"max_results": 10})

if result.success:
    print(result.result)  # {'forms': [...]}
    print(f"Time: {result.execution_time}s | Tokens: {result.token_cost} (~50 cached)")
else:
    print(f"Error: {result.error} | Fix: {result.suggested_resolution}")

CLI:

fastools execute google_forms list_forms --args '{"max_results": 10}'  # Cached <2s/~50 tokens
fastools list-tools  # View cache
fastools auth status  # Check tokens
fastools execute-workflow --file workflow.json  # Multi-tool

Monitoring: fastools telemetry enable (Prometheus /metrics at :8000 for exec/token/sandbox stats).

For workflows/custom tools, see docs/guide.md.

User Stories

US1: Execute Cached Tool (P1 - MVP)

Execute pre-cached tools with 97% token reduction (~50 tokens per operation).

US2: Generate New Tool On-Demand (P2)

Context agent generates tools dynamically with zero manual configuration (~650 tokens first time).

US3: Secure Credential Management (P1 - MVP)

OAuth2 authentication with token storage outside sandbox.

US4: Multi-API Workflow (P3)

Orchestrate multiple cached tools with 85% token savings.

US5: Custom Tool Generation (P3)

Generate non-API utility tools (pure Python functions).

Architecture

fastools/
├── src/
│   ├── executor/       # Core execution and orchestration
│   │   ├── coordinator.py
│   │   ├── sandbox.py
│   │   ├── cache.py
│   │   └── session_manager.py
│   ├── agents/         # Tool generation agents
│   │   ├── context_agent.py
│   │   └── validator.py
│   ├── tools/          # Tool utilities
│   │   └── auth_manager.py
│   └── cli/            # CLI interface
│       └── executor_cli.py
├── tests/
│   ├── contract/       # API contract tests
│   ├── integration/    # End-to-end tests
│   └── unit/           # Unit tests
└── specs/              # Feature specifications
    └── 001-option-f-executor/

Testing

Quick Commands

# Using Make (recommended)
make test              # Run all tests with coverage
make test-unit         # Run unit tests only
make test-integration  # Run integration tests only
make test-contract     # Run contract tests only
make test-fast         # Run tests without coverage (faster)

Manual Testing

# Run all tests
pytest

# Run by marker
pytest -m contract      # Contract tests
pytest -m integration   # Integration tests
pytest -m unit         # Unit tests

# With coverage
pytest --cov=src --cov-report=html

Continuous Integration

The project uses GitHub Actions for automated testing:

• ✅ Python 3.11 and 3.12
• ✅ Ubuntu, macOS, Windows
• ✅ Coverage tracking (Codecov)
• ✅ Security scanning
• ✅ Build validation

View CI status in the Actions tab or check PR status checks.

Performance Metrics

Operation	First Time	Cached	Savings
Single API Call	~3,750 tokens	~50 tokens	97%
Tool Generation	~650 tokens	-	-
10-op Workflow	~3,750 tokens	~550 tokens	85%

Security

FasTools Executor implements defense-in-depth security with multiple layers:

• Sandbox Isolation: RestrictedPython blocks file I/O, network, and system access
• Credential Protection: OAuth2 tokens stored outside sandbox with 0600 permissions
• Memory Limits: 100MB per session, 5GB global limit enforced
• Session Management: Auto-cleanup after 30min idle, 50 session limit
• Permission Validation: Automatic checks for insecure credential permissions
• Cache Integrity: SHA256 checksums with corruption detection and recovery
• Threat Mitigation: Comprehensive protection against sandbox escape, credential theft, and resource exhaustion

Security Documentation:

• Security Model - Architecture, trust boundaries, and threat analysis
• Incident Response - Security incident procedures and playbooks
• Credential Rotation - Rotation procedures and automation
• Operations Guide - Security best practices and troubleshooting

Security Posture:

• ✓ RestrictedPython sandbox tested and validated
• ✓ OAuth2 credential flow end-to-end tested
• ✓ Threat model documented with mitigations
• ✓ Incident response playbooks ready
• ✓ Regular credential rotation procedures
• ✓ Comprehensive security checklist

Development Status

Current Release: Beta (Production-Ready)

Completed Phases:

• Phase 0: Environment Setup
• Phase 1: Build Hygiene & Dependencies
• Phase 2: Auth & Tooling Alignment
• Phase 3: Context Agent & Cache Completeness
• Phase 4: Sandbox & Operational Hardening (full telemetry, timeouts, runbooks)

Test Coverage: 94% (exceeds 80% requirement)

See Production Readiness Plan for details.

Documentation

User Guides:

• Quick Start - Installation and first execution
• Credential Setup - OAuth2 configuration guide
• User Guide - End-to-end usage examples
• API Reference - Python API documentation

Operations:

• Operations Guide - Production deployment procedures
• Security Model - Security architecture and threat model
• Incident Response - Security incident playbooks
• Credential Rotation - Rotation procedures
• Research Adapters - API adapter configuration

Development:

• Release Criteria - Beta/GA requirements
• Production Readiness Plan - Implementation roadmap
• CLAUDE.md - Spec-Driven Development workflow
• Contributing - How to contribute

Contributing

This is a Spec-Driven Development (SDD) project. See CLAUDE.md for development workflow.

Before contributing:

• Review Security Model for security requirements
• Read Release Criteria for quality standards
• Follow test-driven development practices
• Ensure 80%+ test coverage for new code

License

MIT License - See LICENSE file for details.

Contact

• Author: 4xguy
• Email: [e-mail]
• Repository: https://github.com/4xguy/fastools

Contact

• Author: 4xguy
• Email: [e-mail]
• Repository: https://github.com/4xguy/fastools