Metadata-Version: 2.4
Name: core-genai
Version: 1.1.0
Summary: A library that provides common utilities AI-related.
Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
Maintainer: Alejandro Cora González
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/bytecode-solutions/core/core-genai
Project-URL: Repository, https://gitlab.com/bytecode-solutions/core/core-genai
Project-URL: Documentation, https://core-genai.readthedocs.io/en/latest/
Project-URL: Issues, https://gitlab.com/bytecode-solutions/core/core-genai/-/issues
Project-URL: Changelog, https://gitlab.com/bytecode-solutions/core/core-genai/-/blob/master/CHANGELOG.md
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: core-mixins>=3.2.0
Provides-Extra: dev
Requires-Dist: core-dev-tools>=2.0.0; extra == "dev"
Requires-Dist: core-tests>=2.1.0; extra == "dev"
Requires-Dist: types-grpcio>=1.0.0.20260408; extra == "dev"
Provides-Extra: claude
Requires-Dist: anthropic>=0.96.0; extra == "claude"
Provides-Extra: chatgpt
Requires-Dist: openai>=2.32.0; extra == "chatgpt"
Provides-Extra: gemini
Requires-Dist: google-genai>=1.73.0; extra == "gemini"
Provides-Extra: grok
Requires-Dist: openai>=2.32.0; extra == "grok"
Requires-Dist: xai-sdk>=1.11.0; extra == "grok"
Provides-Extra: all
Requires-Dist: core-genai[gemini]; extra == "all"
Requires-Dist: core-genai[grok]; extra == "all"
Requires-Dist: core-genai[chatgpt]; extra == "all"
Requires-Dist: core-genai[claude]; extra == "all"
Dynamic: license-file

core-genai
===============================================================================

A library that provides common utilities AI-related.

===============================================================================

.. image:: https://img.shields.io/pypi/pyversions/core-genai.svg
    :target: https://pypi.org/project/core-genai/
    :alt: Python Versions

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-genai/-/blob/main/LICENSE
    :alt: License

.. image:: https://gitlab.com/bytecode-solutions/core/core-genai/badges/release/pipeline.svg
    :target: https://gitlab.com/bytecode-solutions/core/core-genai/-/pipelines
    :alt: Pipeline Status

.. image:: https://readthedocs.org/projects/core-genai/badge/?version=latest
    :target: https://readthedocs.org/projects/core-genai/
    :alt: Docs Status

.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
    :target: https://github.com/PyCQA/bandit
    :alt: Security

|


Installation
===============================================================================

.. code-block:: bash

    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.


Quick Start
===============================================================================

.. code-block:: bash

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

.. code-block:: bash

    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
