SciTeX GenAI (scitex-genai)

Modality-organised generative-AI provider abstraction for scientific research.

Full Documentation · uv pip install scitex-genai[all]

Problem and Solution

Installation

pip install scitex-genai            # core (LLM providers)
pip install scitex-genai[agent]     # + claude-agent-sdk (forthcoming `agent` submodule)
pip install scitex-genai[litellm]   # + litellm router (preview)
pip install scitex-genai[gateway]   # + Anthropic-compatible model gateway
pip install scitex-genai[ollama]    # + local ollama
pip install scitex-genai[all]       # everything available today

Through the umbrella: pip install scitex[genai]. Requires Python ≥ 3.10.

Claude Code with a Codex subscription backend

The gateway keeps Claude Code as the agent harness. It translates only the model protocol and never executes tools returned by Codex.

export SCITEX_GENAI_GATEWAY_API_KEY="$(openssl rand -hex 32)"
scitex-genai-gateway --host 127.0.0.1 --port 8765

By default the gateway discovers ~/.scitex/agent-container/accounts/openai/*/auth.json. Set the path-separated SCITEX_GENAI_CODEX_HOMES only to override that store. Each configured directory contains an auth.json created by codex login. Tokens remain in those files and are refreshed atomically. Account selection is sticky per session, ranks accounts by Codex usage-window headroom, spreads concurrent sessions, and rotates away from rate-limited accounts. The rotation selector is invoked even for a one-account pool.

Point Claude Code at the service without changing its hooks, skills, tools, or project instructions:

export ANTHROPIC_BASE_URL="http://127.0.0.1:8765"
export ANTHROPIC_API_KEY="$SCITEX_GENAI_GATEWAY_API_KEY"
export ANTHROPIC_MODEL="gpt-5.4"
claude

This integration uses the Codex client subscription transport rather than the separately billed OpenAI API. See the gateway skill for its protocol coverage and operational limitations.

Quick Start

import scitex_genai

ai = scitex_genai.GenAI(model="gpt-4o-mini")
print(ai("Explain neural networks in one sentence."))
print("cost USD:", ai.cost)

# Switch backends without changing the call shape:
ai = scitex_genai.GenAI(model="claude-sonnet-4-6")
ai("Same call, different provider.")

For a runnable walk-through see examples/01_genai.ipynb.

Demo

A runnable provider walk-through (init GenAI, single completion, cost summary, provider switch) lives in examples/01_genai.ipynb. Each cell skips gracefully when the relevant API key is unset.

flowchart LR
    User[your code] -->|GenAI(model)| Factory[scitex_genai.llm.GenAI]
    Factory -->|dispatch| OpenAI[OpenAI]
    Factory --> Anthropic[Anthropic]
    Factory --> Google[Google]
    Factory --> Groq[Groq]
    Factory --> DeepSeek[DeepSeek]
    Factory --> Perplexity[Perplexity]
    Factory --> Llama[Llama]
    OpenAI -.->|tokens / cost| Tracker[BaseGenAI<br/>cost + history]
    Anthropic -.-> Tracker
    Google -.-> Tracker
    Groq -.-> Tracker
    Tracker --> Out[ai&#40;...&#41; · ai.cost · ai.history]

A second examples/example_genai.py runs the same flow as a script and is wired into tests/examples/test_example_genai.py for CI smoke coverage.

Architecture

scitex-genai is organised top-down by modality, not by provider:

scitex-python (umbrella)
    └── scitex.genai ── thin sys.modules-aliasing shim
                        └── scitex_genai (this package)
                              ├── llm/         provider factory ``GenAI``
                              │                 ├── _BaseGenAI         common interface
                              │                 ├── _OpenAI / _Anthropic / _Google /
                              │                 │   _Groq / _DeepSeek / _Perplexity / _Llama
                              │                 ├── _PARAMS            model catalogue
                              │                 ├── _calc_cost         token-cost accounting
                              │                 └── _format_output_func text/markdown formatting
                              ├── gateway/     structured Anthropic ↔ Codex protocol bridge
                              ├── agent/        reserved (claude-agent-sdk wrapper planned)
                              ├── image/        reserved
                              ├── audio/        reserved
                              ├── video/        reserved
                              ├── embed/        reserved
                              └── multimodal/   reserved

Reserved modality namespaces import successfully but raise NotImplementedError on attribute access, so the public import paths are stable as features land. Provider SDKs (openai, anthropic, google-genai, groq) are eager core dependencies today; a follow-up will route llm/ through litellm to demote them to optional and add Ollama out of the box.

Modality layout

Reserved namespaces import successfully but raise NotImplementedError on attribute access — import paths are stable as features land.

4 Interfaces

from scitex_genai import GenAI

ai = GenAI(model="gpt-4o-mini")
print(ai("..."))
print("cost USD:", ai.cost)

Part of SciTeX

scitex-genai is part of SciTeX. Install via the umbrella with pip install scitex[genai] to use as scitex.genai (Python).

import scitex

scitex.genai.GenAI  # same object as scitex_genai.GenAI
scitex.genai.llm    # same object as scitex_genai.llm

scitex.genai delegates to scitex_genai — they share the same API.

The SciTeX system follows the Four Freedoms for Research below, inspired by the Free Software Definition:

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.