gptquerytools 0.0.1

GPTQuery is a modular Python framework for building, orchestrating, and deploying AI-powered tools across domains.

GPTQuery – Modular Tool Framework

GPTQuery is a modular Python framework for building, orchestrating, and deploying AI-powered tools across domains. It provides a clear, scalable architecture for integrating multiple AI providers (OpenAI, Perplexity, Claude, etc.) while maintaining robust error handling, throttling, and dynamic prompting.

The goal of this project is for researchers (or anyone) to create tools derived from custom prompts that can be easily integrated into reserach pipelines.

🚀 Features

• Multi-Provider Support: Unified interface for OpenAI, Perplexity, Claude, and other AI APIs.
• Modular Tool Design: Organize AI functionality into independent, reusable tool families.
• Task Step Separation: Each tool can have multiple steps or functional modules.
• Smart Defaults: Automatically selects optimal models or parameters per provider.
• Safe Data Operations: Uses @requires_columns for safe DataFrame operations.
• Advanced Throttling: Token bucket and adaptive rate-limiters for API management.
• Robust Error Handling: Preserves partial results and gracefully handles failures.
• Cost Optimization: Integrates token management to reduce API costs.

🏗️ Architecture Overview

GPTQuery is organized into three main layers:

1. Core Infrastructure (core/)

   • Clients, logging, and utilities.

2. Processing Utilities (processing/)

   • Helpers for throttling, token management, and miscellaneous runtime functions.

3. Task-Specific Tools (tools/)

   • Each tool lives in its own namespace (e.g., tool_name).
   • Tools are subdivided into submodules/steps:
     • task.py → user-facing functions (run_*)
     • prompt.py → AI prompt definitions
     • log.py → logging utilities
   • The tool’s __init__.py exposes the main public API.

Example: A generic AI tool (tool_example)

tool_example/
├── step_one/
│ ├── task.py # run_step_one
│ ├── prompt.py
│ └── log.py
├── step_two/
│ ├── task.py # run_step_two
│ ├── prompt.py
│ └── log.py
└── init.py # exposes run_step_one, run_step_two

🛠️ Installation

Option 1: Install from PyPI (recommended) Install the latest stable release directly from PyPI using pip:

pip install gptquerytools

Option 2: Clone the repository (for development and custom tools) If you want to contribute or build custom tools based on GPTQuery, clone the repo and install dependencies:

# 1. Clone the repo:
git clone https://github.com/mauriciomm7/gptquery.git
cd gptquery
# 2. Install dependencies:
pip install -r requirements.txt

🎓 Citation

If you use this framework in academic research, please cite:

Mandujano Manríquez, M. (2025). GPTQuery: Modular framework for building and orchestrating AI-powered research tools. GitHub: https://github.com/mauriciomm7/gptquery

@misc{mandujano2025gptquery,
  author       = {Mauricio Mandujano Manríquez},
  title        = {GPTQuery: Modular framework for building and orchestrating AI-powered research tools},
  year         = {2025},
  howpublished = {\url{https://github.com/mauriciomm7/gptquery}},
  note         = {GitHub repository}
}

🤝 Contrubuting

To integrate your tool into GPTQuery, please:

• Place your tool inside the tools/ directory following the existing modular structure.

• Organize your tool with submodules for each step or feature, including:

  • task.py for core functionality,
  • prompt.py for AI prompts,
  • log.py for logging.

• Expose your tool’s API in its __init__.py.

• Write tests and update documentation as needed.

• Submit a pull request with clear explanations of your additions.

Thank you for contributing to GPTQuery!

🙏 Acknowledgments

• CI/CD automation using GitHub Actions — Automating build, test, and deployment workflows
• tokencost — Token cost estimation for language models
• tiktoken — Tokenization library used for accurate token counts
• IPython — Interactive computing environment and enhanced Python shell

📄 License

This project is licensed under the MIT License.