core-genai

A Python library that wraps multiple AI provider SDKs under a single, consistent interface, async-first, with optional synchronous support.

---

Documentation Contents

Index:

• Quick Start
  • Installation
  • Usage
  • Batch jobs

API Reference

• Base Interface
  • Agent Interface
  • Scheduler Interface
  • Contracts
• Gemini
  • Agent
  • Examples
• Claude
  • Agent
  • Examples
• ChatGPT
  • Agent
  • Utilities
  • Examples
• Grok
  • Agent
  • Utilities
  • Examples

Features

• Unified agent interface: all providers share the same IAgent API: analyze, get_text, get_texts, get_cost, and get_metadata.

• Multi-provider support: plug-and-play agents for Google Gemini, Anthropic Claude, OpenAI ChatGPT, and xAI Grok. GrokAgent extends ChatGPTAgent since the xAI API is OpenAI-compatible.

• Async-first, sync-friendly: agents are natively async; wrap any agent with SyncWrapper from core-mixins for transparent synchronous access.

• Normalized usage metadata: get_metadata() always returns a UsageMetadata TypedDict with consistent keys (input_tokens, output_tokens, total_tokens, cost_usd) plus provider-specific optional fields (cached_tokens, cache_creation_tokens, reasoning_tokens).

• Built-in cost estimation: get_cost() computes the USD cost for any response using per-model pricing tables bundled with each agent.

• Factory registration: agents are auto-registered by class name; instantiate any agent with IAgent.create_agent("GeminiAgent", api_key=...).

• Lazy client initialization: the underlying SDK client is created only on first use, so importing an agent has no side effects.

• Batch job support via IScheduler: Gemini, Claude, ChatGPT, and Grok implement schedule_job, check_job_status, and extract_job_results for large-scale asynchronous inference at reduced cost. Users pass simple BatchRequest objects; serialization is handled internally per provider.

• Normalized batch contracts: ScheduledJobMetadata and ScheduledJobResponse are defined once in base.py and shared across all providers, with a common job_id field.

Installation

pip install core-genai
uv pip install core-genai   # Or using UV...
pip install -e ".[dev]"     # For development...

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Write tests for new functionality

4. Ensure all tests pass: python manager.py run-tests

5. Run linting: pylint core_genai

6. Run security checks: bandit -r core_genai

7. Submit a pull request

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

• Documentation: https://core-genai.readthedocs.io/en/latest/

• Repository: bytecode-solutions/core/core-genai

• Issues: bytecode-solutions/core/core-genai/issues

• Changelog: bytecode-solutions/core/core-genai/-/blob/master/CHANGELOG.md

• PyPI: https://pypi.org/project/core-genai/

Support

For questions or support, please open an issue on GitLab or contact the maintainers.

Authors

• Alejandro Cora González - Initial work - alek.cora.glez@gmail.com