fastools-executor 0.1.0
Option F - Self-Evolving Tool Library: Dynamic tool executor with token optimization
License: MIT
Requires Python: >=3.11
Keywords: automation, api, tools, executor, google-workspace

---
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

[![Status](https://img.shields.io/badge/status-ga-green.svg)](docs/release_criteria.md)
[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Test Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen.svg)](https://github.com/4xguy/fastools)

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](docs/security_model.md) and [incident response](docs/incident_response.md).

See [Release Criteria](docs/release_criteria.md) 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)**:
```bash
# 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):
```bash
pip install fastools-executor
```

**Build Distribution** (For Sharing):
```bash
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](https://console.cloud.google.com/apis/credentials) (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](docs/credentials_setup.md).

### Basic Usage

**Python API**:
```python
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**:
```bash
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](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

```bash
# 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

```bash
# 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](docs/security_model.md) - Architecture, trust boundaries, and threat analysis
- [Incident Response](docs/incident_response.md) - Security incident procedures and playbooks
- [Credential Rotation](docs/credential_rotation.md) - Rotation procedures and automation
- [Operations Guide](docs/operations.md) - 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**:
- [x] Phase 0: Environment Setup
- [x] Phase 1: Build Hygiene & Dependencies
- [x] Phase 2: Auth & Tooling Alignment
- [x] Phase 3: Context Agent & Cache Completeness
- [x] Phase 4: Sandbox & Operational Hardening (full telemetry, timeouts, runbooks)

**Test Coverage**: 94% (exceeds 80% requirement)

See [Production Readiness Plan](docs/production_readiness_plan.md) for details.

## Documentation

**User Guides**:
- [Quick Start](#quick-start) - Installation and first execution
- [Credential Setup](docs/credentials_setup.md) - OAuth2 configuration guide
- [User Guide](docs/guide.md) - End-to-end usage examples
- [API Reference](docs/api.md) - Python API documentation

**Operations**:
- [Operations Guide](docs/operations.md) - Production deployment procedures
- [Security Model](docs/security_model.md) - Security architecture and threat model
- [Incident Response](docs/incident_response.md) - Security incident playbooks
- [Credential Rotation](docs/credential_rotation.md) - Rotation procedures
- [Research Adapters](docs/research_adapters.md) - API adapter configuration

**Development**:
- [Release Criteria](docs/release_criteria.md) - Beta/GA requirements
- [Production Readiness Plan](docs/production_readiness_plan.md) - Implementation roadmap
- [CLAUDE.md](CLAUDE.md) - Spec-Driven Development workflow
- [Contributing](#contributing) - How to contribute

## Contributing

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

**Before contributing**:
- Review [Security Model](docs/security_model.md) for security requirements
- Read [Release Criteria](docs/release_criteria.md) for quality standards
- Follow test-driven development practices
- Ensure 80%+ test coverage for new code

## License

MIT License - See [LICENSE](LICENSE) file for details.

## Contact

- **Author**: 4xguy
- **Email**: keithrivas@gmail.com
- **Repository**: https://github.com/4xguy/fastools

## Contact

- **Author**: 4xguy
- **Email**: keithrivas@gmail.com
- **Repository**: https://github.com/4xguy/fastools