Hypothesis Schema

This skill teaches you the hypothesis data format, quality requirements, and how to use the hypex CLI to create and validate hypotheses.

These records remain in the native datastore until the supervisor publishes the completed run with pkde hypex analyze.

Schema Reference

Every hypothesis is a JSON file conforming to schemas/hypothesis.schema.json. The schema uses JSON Schema draft 2020-12.

Required Fields

All of the following fields are required:

Optional Fields

The experiments Array

Each experiment object has three required fields:

{
  "design": "Description of the experimental design",
  "readout": "Expected measurement or readout",
  "est_difficulty": "low|med|high"
}

No additional properties are allowed on experiment objects.

The evidence Array

Each evidence item links a literature record to the hypothesis:

{
  "lit_id": "PMID:38012345",
  "role": "supports",
  "note": "Brief explanation of how this evidence relates to the hypothesis"
}

No additional properties are allowed on evidence objects.

Role definitions:

• supports -- the evidence directly supports the hypothesis claim or mechanism.
• constrains -- the evidence limits the scope or applicability of the hypothesis (e.g., effect is tissue-specific, or only observed in certain conditions).
• contradicts -- the evidence conflicts with the hypothesis. Include contradicting evidence to demonstrate awareness of counterarguments.

The lineage Object

Lineage tracks how a hypothesis was derived:

{
  "parents": [],
  "operator": "null"
}

Operator meanings:

Status Lifecycle

For new hypotheses, always set status to "proposed".

Quality Bar

Every hypothesis you produce must meet these minimum requirements:

1. Title <= 120 characters. Concise and descriptive.
2. At least 1 prediction. Each prediction must be observable and testable.
3. At least 1 experiment. With concrete design, readout, and difficulty estimate.
4. At least 1 evidence item with a lit_id. Every factual claim needs a literature citation. The lit_id must be a real record ID from a PkDE search results -- never fabricate IDs.
5. Falsifiable statement. The statement must be a claim that could be proven wrong by experiment.
6. Causal mechanism. The mechanism must explain why the claim is expected to be true -- not just that it is true.

Hypotheses that fail these requirements will be rejected by schema validation or flagged in review.

Using hypex add-hypothesis

This is the only way to add hypotheses to the datastore. Never write hypothesis JSON files directly.

Command

hypex add-hypothesis [file|-] --run <run-id> --run-dir <run-base>

Arguments

What It Does

1. Reads the hypothesis JSON from the specified file or stdin.
2. Allocates the next sequential ID (e.g., H-0042) via an atomic lockfile-based counter. Any id field in your input is overwritten.
3. Validates the complete hypothesis against hypothesis.schema.json.
4. Writes the file atomically (temp file + rename) to <run-dir>/<run-id>/hypotheses/H-NNNN.json.
5. Prints Added hypothesis: H-NNNN -> <path> to stdout.

Usage Examples

From stdin (preferred for agents):

cat <<'EOF' | hypex add-hypothesis --run my-run --run-dir <run-base> -
{
  "title": "Gut Lactobacillus depletion accelerates tau pathology via vagal signaling",
  "statement": "Depletion of Lactobacillus species in the gut microbiome accelerates tau protein aggregation in the hippocampus through aberrant vagus nerve signaling, contributing to Alzheimer's disease progression.",
  "mechanism": "Lactobacillus metabolites (especially short-chain fatty acids) normally suppress pro-inflammatory cytokine release in the gut epithelium. When Lactobacillus is depleted, increased TNF-alpha and IL-6 travel via the vagus nerve afferents to the brainstem and hippocampus, activating microglia and promoting tau hyperphosphorylation.",
  "predictions": [
    "Germ-free mice colonized with Lactobacillus-depleted microbiomes show increased hippocampal p-tau levels compared to controls",
    "Vagotomy blocks the tau-accelerating effect of gut Lactobacillus depletion"
  ],
  "experiments": [
    {
      "design": "Colonize germ-free mice with defined microbiome communities with and without Lactobacillus. Measure hippocampal p-tau by ELISA at 3, 6, and 9 months.",
      "readout": "p-tau/total-tau ratio in hippocampal lysates",
      "est_difficulty": "med"
    },
    {
      "design": "Perform subdiaphragmatic vagotomy vs sham surgery in Lactobacillus-depleted mice. Compare hippocampal p-tau levels.",
      "readout": "p-tau levels and microglial activation markers (Iba1) in vagotomized vs sham mice",
      "est_difficulty": "high"
    }
  ],
  "evidence": [
    {
      "lit_id": "PMID:38012345",
      "role": "supports",
      "note": "Demonstrates altered gut microbiome composition in Alzheimer's patients with reduced Lactobacillus abundance"
    },
    {
      "lit_id": "arXiv:2401.12345",
      "role": "supports",
      "note": "Computational model predicting vagal signaling as the primary gut-brain axis for neuroinflammation"
    }
  ],
  "focus_area": "Gut-brain axis in neurodegeneration",
  "lineage": {"parents": [], "operator": "null"},
  "status": "proposed",
  "created_by": "hypex-generation-01",
  "epoch": 1,
  "created_at": "2026-09-05T14:30:00Z"
}
EOF

From a file:

hypex add-hypothesis hypothesis-draft.json --run my-run --run-dir <run-base>

Piping (useful in agent workflows):

echo '<hypothesis-json>' | hypex add-hypothesis --run my-run --run-dir <run-base> -

Important Notes

• Do not set the id field -- it is assigned automatically by the command. If you include an id in your JSON, it will be overwritten.
• Do not set the cluster field -- it is assigned later by the proximity agent. The field is optional in the schema.
• Validation happens automatically. If your hypothesis does not conform to the schema, the command will fail with a validation error. Fix the error and retry.
• Writes are atomic. The file is written via temp file + rename, so other agents will never see a partially written hypothesis.

Other Useful hypex Commands

hypex validate

Validate hypothesis (and other artifact) files against their schemas:

# Validate a specific file
hypex validate <run-dir>/hypotheses/H-0042.json

# Validate all artifacts in a run
hypex validate --run my-run --run-dir <run-base>

hypex list

List hypotheses in a run:

# List all hypotheses
hypex list --run my-run --run-dir <run-base>

# Filter by status
hypex list --run my-run --run-dir <run-base> --status proposed

hypex next-id

Allocate the next sequential ID (used internally by add-hypothesis, but available if needed):

hypex next-id hypothesis --run my-run --run-dir <run-base>           # -> H-0043
hypex next-id match --run my-run --run-dir <run-base>                # -> M-0001
hypex next-id review --run my-run --run-dir <run-base> --for H-0043  # -> H-0043.R-01

hypex status

Show a run dashboard:

hypex status --run my-run --run-dir <run-base>

hypex init-run

Initialize a new run (typically done by the supervisor):

hypex init-run my-run --run-dir <run-base> --goal "Explore mechanisms of age-related cognitive decline"

Complete Example: Well-Formed Hypothesis JSON

{
  "title": "Gut Lactobacillus depletion accelerates tau pathology via vagal signaling",
  "statement": "Depletion of Lactobacillus in the gut accelerates hippocampal tau aggregation through vagus nerve-mediated neuroinflammation.",
  "mechanism": "Lactobacillus metabolites suppress gut epithelial cytokine release. Depletion increases TNF-alpha and IL-6 signaling via vagal afferents, activating hippocampal microglia and promoting tau hyperphosphorylation.",
  "predictions": [
    "Germ-free mice with Lactobacillus-depleted microbiomes show elevated hippocampal p-tau",
    "Vagotomy blocks the tau-accelerating effect of Lactobacillus depletion"
  ],
  "experiments": [
    {
      "design": "Colonize germ-free mice +/- Lactobacillus; measure p-tau at 3, 6, 9 months",
      "readout": "p-tau/total-tau ratio in hippocampal lysates",
      "est_difficulty": "med"
    }
  ],
  "evidence": [
    {
      "lit_id": "PMID:38012345",
      "role": "supports",
      "note": "Reduced Lactobacillus in Alzheimer's patients"
    }
  ],
  "focus_area": "Gut-brain axis in neurodegeneration",
  "lineage": {"parents": [], "operator": "null"},
  "status": "proposed",
  "created_by": "hypex-generation-01",
  "epoch": 1,
  "created_at": "2026-09-05T14:30:00Z"
}

Do not include id or cluster -- they are assigned by the system.