Upstream package, source, CLI, and workflows

Research date: 2026-07-23.

Release and integrity status

The latest stable PyPI artifact is hypogenic==0.3.5, uploaded 2025-07-16. PyPI metadata declares Python >=3.10, MIT, and Development Status 4 (Beta). Both files are non-yanked:

• wheel: hypogenic-0.3.5-py3-none-any.whl, 96,169 bytes, SHA-256 f4ee8d7fa433cd59c58e0a8fe7df2f481ae29e7465a1b30ccbdac2c216a1b755;
• sdist: hypogenic-0.3.5.tar.gz, 65,423 bytes, SHA-256 5e1e5590f3612cb606a669909aab117d66577cf078dd56cae0f4123c5e8c44ae.

PyPI trusted-publisher attestations identify repository ChicagoHAI/hypothesis-generation, tag v0.3.5, commit 8c3800ccae155e333fac5b530afa8abdaac38300, and the repository's publish-to-pypi.yml workflow. This is sufficient to recommend a pinned PyPI install, while still requiring ordinary lockfile/hash controls.

The default master commit observed was bd37a3129a2f98ee586f545a57b10b59496eedad (2025-07-17). It is four commits ahead of the release tag; the changed files add logging/visualization support and a debug option. The README.md and pyproject.toml blobs are identical between v0.3.5 and that master revision, and the source version remains 0.3.5. No newer GitHub release or PyPI version was found.

Interpretation: artifact, source tag, metadata, and README provenance align. The branch has small unreleased logging changes, so do not substitute branch tip for the release.

Declared dependency surface

The default artifact declares broad compatible-release ranges around:

• NumPy 1.26.3, pandas 2.1.4, datasets 2.16.1;
• Transformers 4.45.1, PyTorch 2.4.0, Accelerate 0.33.0;
• OpenAI 1.40.3, Anthropic 0.32.0, Redis 5.0.1;
• scikit-learn 1.3.0, matplotlib 3.8.0, PuLP 2.9.0;
• PyYAML 6.0.1 and several document/web packages.

The dev extra adds vLLM 0.6.2 and vllm-flash-attn 2.6.2. Resolve this in an isolated environment. The package declaration says Python >=3.10 but does not state an upper bound; actual resolver/platform support is constrained by those older compiled dependencies.

Verified import and registry surface

The package root does not export BaseTask. The source imports used by its own examples include:

from hypogenic.tasks import BaseTask
from hypogenic.prompt import BasePrompt
from hypogenic.extract_label import extract_label_register
from hypogenic.LLM_wrapper import llm_wrapper_register

These are source-level interfaces in 0.3.5, not a separately versioned public API contract. Prefer the pinned examples when writing custom code.

Registered model wrapper types:

• gpt: OpenAI Python client and chat-completions calls;
• claude: Anthropic Python client and Messages calls;
• huggingface: local Transformers text-generation pipeline;
• vllm: local vLLM generation.

Important local-provider limitation: hypogenic.LLM_wrapper.__init__ imports both local wrappers from one module, and that module raises when vllm is absent. The exception is caught, leaving both huggingface and vllm unregistered. Thus the base install's CLI advertises both choices, but local wrapper registration depends on the dev path in this release.

The hosted wrappers instantiate OpenAI() and Anthropic() without an explicit key, so their SDK-standard names are OPENAI_API_KEY and ANTHROPIC_API_KEY. No other credential names were found in the wrapper code.

CLI entry points and limitations

pyproject.toml declares:

hypogenic_generation = hypogenic_cmd.generation:main
hypogenic_inference  = hypogenic_cmd.inference:main

Use their pinned --help output as the command contract. Do not copy the old skill's --config, --method, --num_hypotheses, --hypotheses, --test_data, or --papers examples; those flags are not present in the 0.3.5 entry-point parsers.

Verified generation options include:

• --task_config_path, --model_name, --model_path, --model_type;
• train/validation/test counts and seed;
• bank size, initialization, update, replacement, concurrency, Redis/cache, output, restart, and logging options;
• max_tokens and temperature are accidentally declared as positional arguments despite having defaults. Treat them as required by this parser and confirm with --help.

Verified inference options include:

• --task_config_path, --hypothesis_file, provider/model options;
• seeds, split counts, validation switch, inference style, adaptive settings, cache/Redis, concurrency, logging, token cap, and temperature.

Known source quirks relevant to reproducibility:

• generation defaults combine model_type=gpt with a Meta-Llama model name; defaults are not a safe executable plan;
• importing the generation entry-point module on Python 3.13 emits a SyntaxWarning for an invalid \{ escape in one help string;
• the GPT wrapper's embedded cost table has only gpt-4o-mini, gpt-4o, o1, and o3-mini, and uses direct lookup. It is not current pricing or general model support;
• generation has a TODO instead of reporting session cost;
• the inference entry point computes per-seed accuracy/F1 but does not append them to its averaging lists, so its final averaged log values are not reliable;
• the README says new-task command-line support is planned for a later release;
• the README's generic task snippet swaps validation/test filenames, while pinned dataset configs use distinct, correctly named split files.

These mismatches are why this skill provides planning/auditing tools but does not auto-run the upstream CLI.

Task and dataset support

The label-extractor registry contains handlers for:

• default, AI-generated-content detection, headline comparison, deceptive reviews, retweets, shoe color, Yelp rating, persuasive pairs, Dreaddit stress, election, preference, and admission tasks.

A registered label parser is not proof of complete end-to-end task support. The current HypoBench dataset repository covers seven real-world task families (deception, AI-content detection, persuasive arguments, mental stress, headline engagement, retweets, and paper citations) plus synthetic task families and variants. Use the config included with the exact pinned dataset revision.

Dataset JSON is column-oriented: every field maps to a list and all lists must have equal length. BaseTask joins each configured path to the task config's directory, samples rows, and returns pandas data frames. Train, validation, test, and optional OOD files remain distinct only if the config preserves them.

Generation, outputs, and evaluation

Default HypoGeniC:

1. creates candidate hypotheses from batches of labeled training examples;
2. evaluates hypotheses through LLM-based label inference;
3. updates accuracy/reward/visit statistics;
4. generates replacements after accumulated difficult examples;
5. writes intermediate/final banks.

The saved bank is a JSON object keyed by hypothesis text. Each value serializes SummaryInformation:

{
  "hypothesis": "candidate text",
  "acc": 0.0,
  "reward": 0.0,
  "num_visits": 0,
  "correct_examples": []
}

Literature/HypoRefine examples additionally preprocess supplied PDFs, summarize papers, refine data/literature hypotheses, and create HypoRefine, literature-only, and union banks. This is an example-script workflow rather than a --method hyporefine flag on the packaged generation entry point.

Default inference sorts the bank by stored accuracy, applies the best entry to the selected split, and returns prediction/label lists internally. The CLI logs per-seed accuracy, F1, and wrong indices; it does not define the strict result artifact used by this skill. assets/result.example.json is a skill-local, model-free interchange schema.

The upstream papers evaluate classification utility, human decision support, generalization, and hypothesis-discovery behavior. Those evaluations do not turn generated text into causal or experimentally confirmed scientific evidence.