Metadata-Version: 2.4
Name: cta-kernel
Version: 0.1.0
Summary: Computational text analysis with inspectable GraphSpec execution.
Author-email: Aris Xanthos <aris.xanthos@unil.ch>
Maintainer-email: Aris Xanthos <aris.xanthos@unil.ch>
License-Expression: MIT
Project-URL: Repository, https://github.com/axanthos/cta_kernel
Project-URL: Issues, https://github.com/axanthos/cta_kernel/issues
Keywords: computational humanities,computational text analysis,provenance,research software
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# `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:

```bash
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:

```text
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:

<!-- exec:id=readme-quick-start kind=python expect=output -->
```python
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)
```

```text
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](docs/concepts.md) for the layer
boundaries, [GraphSpec 0.1](docs/graphspec.md) for the serialized graph
contract, and [Persistent runtime](docs/persistent-runtime.md) for the
long-lived `KernelRuntime` integration guide.

## Core concepts

- A [**GraphSpec**](docs/graphspec.md) is the typed, versioned description of a
  computational graph.
- A [**profile**](docs/comhum-profile.md) constrains admissible operators,
  ports, parameters, and scope.
- An [**operator** and **port**](docs/concepts.md#conceptual-map) define one
  typed analytic step and its connections.
- [**Scope**](docs/concepts.md#conceptual-map) records the declared epistemic
  labels attached to the analysis.
- [**Evidence** and **provenance**](docs/concepts.md#conceptual-map) record a
  typed payload and its computational derivation.
- A [**claim**](docs/comhum-profile.md#threshold-and-comparison-claims)
  evaluates one bounded evidential statement under the active profile.
- A [**robustness evaluation**](docs/comhum-profile.md#robustness-contract)
  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:

```text
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:

<!-- exec:id=readme-cli-invocation kind=bash expect=noerror -->
```bash
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](docs/cli.md) for every
supported option and exit code, and [Errors](docs/errors.md) 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`](CITATION.cff), and the software is
licensed under the [`MIT License`](LICENSE). See [`CHANGELOG.md`](CHANGELOG.md)
for release history. See [Development](docs/development.md) for contributor
setup, the spec-first and test-first method, and build/install validation,
and [Compatibility](docs/compatibility.md) 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.
