Metadata-Version: 2.5
Name: endless-learning
Version: 0.0.2
Summary: Knowledge-graph-driven synthesis of verifiable RL training tasks (open reproduction of the Kimi K3 task-synthesis pipeline)
Project-URL: Repository, https://github.com/alexngai/endless-learning
Project-URL: Documentation, https://github.com/alexngai/endless-learning/tree/main/docs
Author: endless-learning contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,knowledge-graph,llm,reinforcement-learning,task-synthesis
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: ddgs>=9.0; extra == 'all'
Requires-Dist: huggingface-hub>=0.25; extra == 'all'
Requires-Dist: litellm>=1.40; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: numpy>=1.26; extra == 'all'
Requires-Dist: openai>=1.40; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: ddg
Requires-Dist: ddgs>=9.0; extra == 'ddg'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: hub
Requires-Dist: huggingface-hub>=0.25; extra == 'hub'
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == 'litellm'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: semantic
Requires-Dist: numpy>=1.26; extra == 'semantic'
Provides-Extra: verifiers
Requires-Dist: verifiers>=0.3; extra == 'verifiers'
Description-Content-Type: text/markdown

# endless-learning

Generate your own RL training tasks — and verify they are worth training on.

`endless-learning` builds a concept graph by exploring the web, mines
verifiable tasks from it, and gates every task through execution: a task ships
only if something can actually check the answer. Two kinds of task are live —
deep-search questions grounded in a frozen document corpus, and executable
coding instances mined from real repositories.

It is an open reproduction of the knowledge-graph task synthesis described in
the Kimi K3 technical report
([arXiv 2607.24653](https://arxiv.org/abs/2607.24653)).

**Scope:** this is the data engine — graph, mining, verification, and versioned
datasets that ship with their reward functions and environments. There is no
training loop; trainers own the rollout loop.

## What you can do with it

| | |
|---|---|
| **Grow a concept graph** | Agents explore outward from a seed pack, expanding a deduplicated concept DAG. Three packs ship with the package; bring your own as a TOML file. |
| **Mine deep-search questions** | Questions grounded in a content-addressed corpus, gated V1–V5: grounded, unique, non-trivial, solvable, stable. |
| **Mine executable coding tasks** | SWE-bench-shaped instances from real repos, validated by running the tests: the oracle must fail on the broken state and pass on the fixed one. |
| **Re-verify offline** | Every dataset re-checks with no network and no model calls, against pinned images and hashed documents. |
| **Export to trainers** | verifiers tasksets, chorus `TaskRecord` registries, and Harbor task directories — each checked against the consumer's own code. |

## Install

```bash
pip install 'endless-learning[all]'
```

Python 3.11+. Extras, if you would rather pick: `[anthropic]` `[openai]`
`[litellm]` `[ddg]` `[mcp]` `[hub]` `[semantic]` `[verifiers]`.

Docker is required for the coding domain only. Everything else runs locally.

## Quickstart

Nothing here downloads a prebuilt graph — the package is the engine, and every
artifact is produced by your run, in your workspace.

```bash
mkdir my-graph && cd my-graph
endless init                                            # endless.toml + .endless/
endless kg expand --seeds knowledge --budget-nodes 0    # plant a seed pack, no keys needed
endless kg stats
```

Seeding is local. **Growing** the graph calls a model and a search backend, so
set the credentials your `endless.toml` roles name, then raise the budget:

```bash
export ANTHROPIC_API_KEY=...          # or whichever provider endless.toml selects
endless kg expand --budget-nodes 50   # agents explore outward from the seeds
```

## Deep-search questions

Sample the graph, write questions against retrieved documents, and keep only
what survives the gate. The corpus is content-addressed, so a question that
passes today re-verifies tomorrow against the same bytes.

```bash
endless synth run --n 20 --workers 6    # sample → write → gate → tasks.jsonl
endless dataset verify                  # offline: no network, no model calls
endless dataset export-verifiers        # verifiers-v1 taskset package
```

## Coding tasks

Onboard a repository into a pinned image with a flake-screened test ledger,
then mine instances from its history. Every instance is validated by execution
against two states of the repo before it is allowed to exist.

```bash
endless coding select --n 10                   # graph concepts → candidate repos
endless coding onboard --repo <url>            # pinned image + test ledger
endless coding mine --since 2024-01-01         # mine instances → dual-state validation
endless coding verify-instances                # replay every instance from its images
```

Three families are built, differing in what the model is asked to do:

| family | the job | where instances come from |
|---|---|---|
| `code-bugfix` | fix the code | a commit that touches source and tests together |
| `code-testgen` | write the test | inverts a bugfix instance — your test must fail before the fix and pass after |
| `code-evolution` | implement the change | a merged pull request, scoped so the task is a coherent unit of work |

```bash
endless coding mine-testgen        # invert released bug fixes
endless coding mine-evolution      # mine merged pull requests
```

Export to whichever harness you train against:

```bash
endless coding export-chorus                       # chorus TaskRecord registry
endless coding export-harbor                       # Harbor task directories
endless coding publish-images --registry <prefix>  # retag; push only with --push
endless coding export-tree                         # one file per instance, for a git-backed corpus
```

## What ships, and what does not

**Datasets are outputs of your run, and are not distributed here.** A
search-QA record cites document hashes; a coding instance names a pinned
image. Without the corpus and the images neither re-verifies, so shipping the
JSONL alone would be shipping a claim with its evidence removed. `endless
dataset verify` re-verifies against *your* corpus, built by *your* runs.

## What to expect

Measured results, including the ones that did not go our way — worth reading
before you plan around this:

- **Difficulty is expensive to measure and noisy.** Per-task pass rate is
  ±0.24 at 5 rollouts, exactly binomial. Aggregate over 30+ tasks; never read
  a single task's label.
- **The graph does not make tasks hard.** Four independent levers each
  improved a question's shape and left the mean pass rate at 0.88. What the
  graph is actually for is coverage and checkable grounding.
- **Onboarding is mechanical, and bounded.** Roughly 83% success on curated
  mainstream Python, near 0% on the long tail the graph selects.
- **A task's statement is the binding constraint, not its difficulty.** In one
  80-episode run every instance scored 0.000, not because the work was hard
  but because the statements under-specified what the tests check. Re-deriving
  each statement from what the pull request actually merged moved one instance
  from a flat 0.167 to a mean of 0.938.
- **Offline re-verification holds.** 25/25 on the search set, 8/9 on coding —
  the miss being a real catch, an oracle whose verdict depended on set
  ordering.

## Docs

Design notes, decisions and measured results live in [`docs/`](https://github.com/alexngai/endless-learning/tree/main/docs) as a
numbered series — start at [docs/000-overview.md](https://github.com/alexngai/endless-learning/blob/main/docs/000-overview.md).
