.. core-genai documentation master file, created by
   sphinx-quickstart on Wed Apr 22 10:03:54 2026.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

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

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

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

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


Documentation Contents
-------------------------------------------------------------------------------

.. toctree::
   :maxdepth: 2
   :caption: Index:

   quickstart

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api/base
   api/gemini
   api/claude
   api/chatgpt
   api/grok


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
  :class:`~core_genai.base.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**: :class:`~core_genai.base.ScheduledJobMetadata`
  and :class:`~core_genai.base.ScheduledJobResponse` are defined once in
  ``base.py`` and shared across all providers, with a common ``job_id`` field.


Installation
-------------------------------------------------------------------------------

.. code-block:: bash

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