Metadata-Version: 2.5
Name: endless-learning
Version: 0.0.1
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'
Description-Content-Type: text/markdown

# endless-learning

An open-source reproduction of knowledge-graph-driven RL task synthesis, as
described in the Kimi K3 technical report
([arXiv 2607.24653](https://arxiv.org/abs/2607.24653)): a self-evolving
concept hierarchy that agents expand through web exploration, from which
verifiable RL training tasks are mined, grounded in pinned real-world
materials, and gated through an explicit verification contract.

**v0 scope:** the data engine — graph construction, task mining,
verification, and versioned datasets that ship with their reward functions
and environments. No RL training loop; trainers own the rollout loop
([docs/006](docs/006-agent-environments.md)).

Two task domains are live:

- **Deep-search QA** — questions grounded in a frozen, content-addressed
  corpus, gated V1–V5 (grounded / unique / non-trivial / solvable / stable),
  every pass rate stamped with the versioned environment it was measured in.
- **Coding** — SWE-bench-shaped instances mined from real repositories
  (PR mirroring: the commit's own test changes are the oracle), validated by
  execution against dual states (the oracle must fail on the broken image
  and pass on the fixed one), flake-screened per state, and offline
  replayable from pinned container images.

## What is measured, and what is not

The design docs record the negative results where they happened; this is the
short version, because it is the honest way to read everything above.

| claim | status |
|---|---|
| Tasks re-verify offline, with no network and no model calls | **measured** — 25/25 on the search set; coding **8/9**: the replay gate caught an oracle whose verdict depended on set ordering, deterministic and correctly *failing* since `PYTHONHASHSEED` was pinned (docs/005 M4) |
| Coding instances discriminate: the oracle fails broken and passes fixed | **measured** — including through Harbor's own harness (oracle → 1, nop → 0) |
| Onboarding is mechanical | **measured, and bounded** — ~83% on curated mainstream Python, ~0% on the long tail the graph selects |
| The knowledge graph makes tasks *hard* | **false** — four independent levers (obfuscation, multi-document grounding, forced computation, method selection) each improved the question's shape and left the mean pass rate at 0.88, with ~70% of tasks solved on every rollout |
| The knowledge graph is what makes coverage broad and grounding checkable | **its actual job** — and the reason [docs/008](docs/008-executable-tasks.md) moves difficulty into the task format rather than the question |

Difficulty measurement is expensive and noisy: per-task pass rate is ±0.24 at
5 rollouts (measured, and exactly binomial). Aggregate over ≥30 tasks; never
read a single task's label.

## This repo is the engine, not the dataset

Emitted datasets are outputs of running the pipeline, and they are not
distributed here. A search-QA record cites content-addressed document hashes;
a coding instance names a pinned container 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.

Making those artifacts portable — a corpus bundle carrying only the documents
a dataset cites, and published images — is the prerequisite for releasing
datasets at all.

Datasets compile into three consumer-validated interchange formats
([docs/007](docs/007-task-domains-and-interchange.md)): a
[verifiers](https://github.com/PrimeIntellect-ai/verifiers) taskset package,
chorus `TaskRecord` registries, and
[Harbor](https://github.com/laude-institute/harbor) task directories — each
verified against the consumer's own code, not its documentation.

## Quickstart

Build your own graph. Nothing here downloads ours — the package is the
engine, and every artifact below is produced by your run, in your workspace.

```bash
pip install 'endless-learning[all]'   # or pick extras: [anthropic] [openai] [litellm] [ddg]

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

Three seed packs ship with the package — `knowledge`, `quantitative`,
`earth-systems` — and `--seeds` also takes a path, so your own pack is a TOML
file with a `seeds` list. Seeding is local; **growing** the graph calls a
model and a search backend, so set the credentials your `endless.toml` roles
name and raise the budget:

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

From there `endless synth run` mines search-QA tasks from the graph, and the
`endless coding` commands onboard repositories into pinned images and mine
executable instances — see [The pipelines](#the-pipelines). Docker is
required for the coding domain only.

## Install (development)

```bash
pip install -e '.[dev]'      # extras: [anthropic] [openai] [litellm] [mcp] [all]
endless --help
```

## The pipelines

```bash
# knowledge graph
endless init                                       # create a workspace here
endless kg expand --seeds knowledge                # grow the concept DAG
endless kg stats

# search-QA synthesis
endless synth run --n 20 --workers 6               # sample → write → gate → tasks.jsonl
endless dataset verify                              # offline re-verification (no network, no models)
endless dataset export-verifiers                    # verifiers-v1 taskset package

# coding domain
endless coding select --n 10                        # KG concepts → candidate repos (star-filtered)
endless coding onboard --repo <url>                 # pinned image + flake-screened test ledger
endless coding mine --since 2024-01-01              # PR-mirror candidates → dual-state validation
endless coding verify-instances                     # replay every instance from its pinned images
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)
```

## Design docs

The design lives in [`docs/`](docs/) as a numbered series — start at
[docs/000-overview.md](docs/000-overview.md). Decisions and measured
results (including the negative ones) are recorded where they happened.

| Doc | Topic |
|---|---|
| [000](docs/000-overview.md) | Vision, scope, architecture, decision log |
| [001](docs/001-paper-notes.md) | The K3 report, reconciled against the actual PDF |
| [002](docs/002-knowledge-graph.md) | Concept DAG: schema, expansion, dedup, storage |
| [003](docs/003-retrieval-and-corpus.md) | Pluggable retrieval, caching, content-addressed corpus |
| [004](docs/004-task-synthesis.md) | Sampling, task writing, the V1–V5 gate, difficulty |
| [005](docs/005-roadmap.md) | Milestones, acceptance criteria, measured results |
| [006](docs/006-agent-environments.md) | Environments: action space + reward, versioned specs |
| [007](docs/007-task-domains-and-interchange.md) | Task domains, mining sources, interchange adapters |
| [008](docs/008-executable-tasks.md) | Executable tasks outside the coding domain |
| [009](docs/009-task-representation.md) | Task families, substrate tags, and what keeps them honest |
