cta_kernel

cta_kernel is a headless computational-text-analysis kernel for specifying, executing, and inspecting typed analysis graphs.

The first supported release target is 0.1.0 on Python 3.11 or later. The package is currently being prepared for that release. A GraphSpec describes a typed analysis graph; the runtime validates it against a profile and executes its operations, connections, parameters, and declared epistemic scope.

This package is one bounded computational layer. It is distinct from the planned cta_orange interface and from the ComHUM replication package, and it does not by itself constitute the wider formal theory of computational text analysis.

Installation

After the first release is published:

python -m pip install cta-kernel

The wheel installs the reusable cta_kernel library and the cta-kernel command. The public example files live in the repository and source distribution; a wheel cannot create an examples/ directory in an arbitrary working directory. Clone the repository or unpack the source distribution before running the example paths below.

Quick start

The synthetic fixture contains 14 emoji-string occurrences. A string is a strict repetition when all its emoji tokens are identical. Six occurrences contain three emoji; five of those are strict repetitions. Eight occurrences contain two emoji; two of those are strict repetitions. The example compares these proportions with length three as A and length two as B:

A = 5 / 6
B = 2 / 8
delta = A - B = 7 / 12

Run the GraphSpec from the root of a repository clone or unpacked source distribution:

from cta_kernel import run_graphspec

result = run_graphspec("examples/comhum_minimal_graphspec.json")
claim = result.output("claim_compare", "claim")

print(claim.payload["status"])
print(claim.payload["delta"])
print(claim.prov.scope)

SUPPORTED
0.5833333333333334
{'dataset_id': 'invented_comhum_minimal_fixture_v1', 'slice_id': 'all_invented_occurrences'}

This prints a SUPPORTED claim, a difference of approximately 0.5833, and the declared dataset and slice labels. The result retains every output produced in that run. Each output is typed evidence with a stable identifier, an operator-defined payload, and provenance recording its origin, scope, upstream digests, determinism, and transformation chain. A claim adds a status and its supporting scalar values. When one persistent runtime executes an unchanged graph again, its RunLog records cache hits rather than recomputed nodes.

Two API levels

Scripts and notebooks normally use run_graphspec(...) for one-shot execution. Long-lived clients use KernelRuntime.for_profile(...), retain the runtime across calls to run(...), and inspect evidence through the supported runtime and result methods. See Core concepts for the layer boundaries, GraphSpec 0.1 for the serialized graph contract, and Persistent runtime for the long-lived KernelRuntime integration guide.

Core concepts

• A GraphSpec is the typed, versioned description of a computational graph.
• A profile constrains admissible operators, ports, parameters, and scope.
• An operator and port define one typed analytic step and its connections.
• Scope records the declared epistemic labels attached to the analysis.
• Evidence and provenance record a typed payload and its computational derivation.
• A claim evaluates one bounded evidential statement under the active profile.
• A robustness evaluation checks whether a decision persists across specified weighting policies.

These Python objects instantiate the current bounded computational layer. The wider formal theory constrains which analyses and interpretations are admissible; it is not reducible to the implementation.

Synthetic emoji-string example

ComHUM 2026 is the workshop for which the accepted paper Executable claims for graph-based text analysis: from exploration to auditability was prepared. The paper demonstrates the kernel and a separate Orange interface through an emoji-string case study. The example bundled here illustrates the kernel-side computation with invented data; it is neither the paper's data nor its exact replication workflow.

The graph loads the 14 occurrence rows, groups identical strings while preserving their occurrence mass, splits each string on -, and selects the length-three and length-two subsets. Within each subset, variety == 1 identifies strict repetitions: strings whose segmented emoji tokens are all the same. The resulting quantities are therefore:

• A: the proportion of strict repetitions among the six length-three occurrences, namely 5 / 6;
• B: the proportion of strict repetitions among the eight length-two occurrences, namely 2 / 8.

The GraphSpec represents these subsets with nodes named len3 and len2 and uses them as the denominator views for the two proportions. Its fixed comparison orientation is:

A = len3
B = len2
delta = A - B

The current comparison is a profile-specific template created for this bounded demonstration. Its compatibility checks must not be interpreted as general validity conditions for every possible scalar comparison.

Command line

From the same source-bundle root:

cta-kernel run examples/comhum_minimal_graphspec.json --show-claim --show-provenance

The equivalent module form is python -m cta_kernel run .... The command can also dump complete NODE.PORT outputs and exposes tracebacks only when --debug is requested. See Command-line interface for every supported option and exit code, and Errors for the typed failures the command and the Python API share.

Boundaries and destinations

Use cta_kernel for headless graph execution and evidence inspection. cta_orange is the separate add-on that will expose the same kernel through the Orange visual data-mining interface. The paper-specific ComHUM replication package will contain the authoritative published workflow, controlled-data preparation instructions, pinned package releases, and expected results.

Citation, licence, and development

Citation metadata is in CITATION.cff, and the software is licensed under the MIT License. See CHANGELOG.md for release history. See Development for contributor setup, the spec-first and test-first method, and build/install validation, and Compatibility for the 0.1.x version and deprecation policy. Public repository and issue-tracker links will be added before the 0.1.0 release gate.