core-genai

A library that provides common utilities AI-related.

Installation

pip install core-genai
uv pip install core-genai

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 (GeminiAgent)

  • Anthropic Claude (ClaudeAgent)

  • OpenAI ChatGPT (ChatGPTAgent)

  • xAI Grok (GrokAgent, inherits from ChatGPTAgent)

• 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 all implement schedule_job, check_job_status, and extract_job_results for large-scale asynchronous inference at reduced cost. Users pass simple BatchRequest objects; the agents handle provider-specific serialization internally.

• Normalized batch contracts: ScheduledJobMetadata and ScheduledJobResponse are defined once in base.py and shared across all providers, with a common job_id field and optional timing fields (start_time, end_time) for providers that expose them.

• Prompt evaluation (core_genai.prompt): model-as-judge evaluation engine for comparing prompt versions. Generates synthetic test datasets, runs prompt functions concurrently via ThreadPoolExecutor, grades outputs against user-defined criteria, and renders an HTML report with per-case scores, strengths, weaknesses, and pass-rate statistics.

Quick Start

pip install core-genai
pip install -e ".[dev]"    # For development

Testing Across Python Versions

A helper script is included to run all functional tests against every virtual environment matching .venv* in the project root, making it easy to verify compatibility across Python versions (CPython and PyPy):

bash tests/run_all_venvs.sh

Each .venv* directory must already exist and have the package installed. The script iterates over every environment, runs all scripts under tests/functional/, prints the exit code for each, and moves on to the next.

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: https://gitlab.com/bytecode-solutions/core/core-genai

• Issues: https://gitlab.com/bytecode-solutions/core/core-genai/-/issues

• Changelog: https://gitlab.com/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