# LoopX Capabilities Explained: How to Use Issue‑Fix, Content‑Ops, and ML‑Experiment

> Explore LoopX capabilities like issue-fix content-ops and ml-experiment. Learn how to use these modular workflows via CLI or programmatically to streamline your projects. Discover LoopX today.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-07

---

**TLDR:** LoopX provides three core capabilities—**issue‑fix**, **content‑ops**, and **ml‑experiment**—each exposed as modular workflows under `loopx/capabilities/` and invoked via the `--capability‑route` CLI flag or programmatically through packet builders and runners.

The `huangruiteng/loopx` repository delivers a modular capability system that encapsulates complex automation into reusable components. These **LoopX capabilities** enable developers to resolve GitHub issues, manipulate web content surfaces, and execute machine learning experiments through a unified interface. Each capability registers itself in a central catalog and exposes both CLI entry points and Python APIs for flexible integration.

## What Are LoopX Capabilities?

LoopX capabilities are self‑contained workflow modules stored under `loopx/capabilities/`. According to the source code, each capability registers a **catalog entry** in [`loopx/capabilities/catalog.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/catalog.py) containing a unique ID, description, and path to documentation. The system uses a **packet‑based architecture** where capabilities exchange JSON‑serializable data, enabling composition and replay through the state projection system ([`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py)).

## Overview of the Three Core Capabilities

### Issue‑Fix Capability

The **issue‑fix** capability automates the full lifecycle of public GitHub issues—from candidate discovery and feasibility checking to reviewer requests and PR creation. It resides in `loopx/capabilities/issue_fix/` and provides packet builders such as `build_issue_fix_feasibility_packet` and validators like `validate_issue_fix_feasibility_packet`. Users invoke this capability via `--capability-route issue-fix` or call specific workflow templates directly.

### Content‑Ops Capability

The **content‑ops** capability supplies utilities for web content extraction and surface manipulation. Located in `loopx/capabilities/content_ops/`, it includes the `surface` module ([`loopx/capabilities/content_ops/surface.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/content_ops/surface.py)) and connectors like [`loopx/capabilities/value_connectors/social_profile.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/value_connectors/social_profile.py). This capability handles social‑browser extraction and surface rendering, activated through `--capability-route content-ops`.

### ML‑Experiment Capability

The **ml‑experiment** capability provides a lightweight framework for reproducible machine learning workflows. Implemented in `loopx/capabilities/ml_experiment/`, it exposes helper functions such as `run_experiment` and `log_metrics` through [`loopx/capabilities/ml_experiment/runner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/ml_experiment/runner.py). Developers activate it with `--capability-route ml-experiment` to execute training, evaluation, and automated reporting tied to LoopX's state‑projection system.

## How to Invoke LoopX Capabilities

LoopX supports two primary invocation patterns: CLI routing for command‑line usage and programmatic access for Python applications.

**CLI Routing:**

The top‑level `loopx` CLI parses the `--capability-route` flag in [`loopx/cli_commands/ready_score.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/ready_score.py) and [`loopx/project_map.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/project_map.py), dispatching commands to the appropriate module. For example:

- `loopx --capability-route issue-fix ...`
- `loopx --capability-route content-ops ...`
- `loopx --capability-route ml-experiment ...`

**Programmatic Access:**

Each capability exposes packet builders and runners that can be imported directly. These functions create validated JSON packets that capabilities exchange via the state projection system.

## Practical Code Examples

### Issue‑Fix: Creating a Feasibility Packet

The following example demonstrates building and validating a feasibility packet for GitHub issue #42:

```python
from loopx.capabilities.issue_fix.feasibility import (
    build_issue_fix_feasibility_packet,
    validate_issue_fix_feasibility_packet,
)

# Build a packet for issue #42 in the current repository

packet = build_issue_fix_feasibility_packet(
    issue_ref="#42",
    repo_owner="myorg",
    repo_name="myrepo",
)

# Validate the packet before proceeding

validation = validate_issue_fix_feasibility_packet(packet)
assert validation["is_valid"], validation["errors"]

```

See the full flow in [`tests/capabilities/test_issue_fix_feasibility.py`](https://github.com/huangruiteng/loopx/blob/main/tests/capabilities/test_issue_fix_feasibility.py).

### Content‑Ops: Rendering a Social Profile Surface

Extract and render a LinkedIn profile surface using the social profile connector:

```python
from loopx.capabilities.content_ops.social_browser_x import fetch_profile_surface

# Pull a public LinkedIn profile (the connector knows the source schema)

surface = fetch_profile_surface(username="alice")

# The surface can be rendered as markdown or fed into another capability

print(surface.render_as_markdown())

```

The connector implementation lives in [`loopx/capabilities/value_connectors/social_profile.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/value_connectors/social_profile.py).

### ML‑Experiment: Running a Training Loop

Execute a reproducible experiment using the ML runner:

```python
from loopx.capabilities.ml_experiment.runner import run_experiment

# Define a simple experiment configuration (data, model, metrics)

config = {
    "data_path": "data/train.csv",
    "model": "sklearn.linear_model.LogisticRegression",
    "metrics": ["accuracy", "f1"]
}

# Execute the experiment; results are automatically logged into LoopX state

results = run_experiment(config)
print("Experiment finished – metrics:", results["metrics"])

```

The experiment driver is located in [`loopx/capabilities/ml_experiment/runner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/ml_experiment/runner.py).

## Key Files and Architecture

Understanding the file structure helps navigate the capability system:

- [`loopx/capabilities/catalog.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/catalog.py) – Central registry containing capability IDs, descriptions, and documentation paths.
- `loopx/capabilities/issue_fix/` – Full implementation including packet builders, CLI templates, and feasibility validators.
- `loopx/capabilities/content_ops/` – Modules for content extraction, surface rendering, and social‑browser integration.
- `loopx/capabilities/ml_experiment/` – Framework for defining, running, and logging ML experiments.
- [`loopx/cli_commands/ready_score.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/ready_score.py) – Parses `--capability-route` and dispatches to appropriate command packs.
- [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) – Records all capability actions for replay and auditing.
- [`docs/capabilities/issue-fix/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/capabilities/issue-fix/README.md) – User‑facing guide for issue automation.
- [`docs/capabilities/content-ops/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/capabilities/content-ops/README.md) – Documentation for content operations.
- [`docs/capabilities/ml-experiment/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/capabilities/ml-experiment/README.md) – Overview of machine learning experiments.

## Summary

- LoopX capabilities are modular workflows registered in [`loopx/capabilities/catalog.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/catalog.py).
- **Issue‑fix** automates GitHub issue resolution via packet builders like `build_issue_fix_feasibility_packet`.
- **Content‑ops** handles web extraction and surface manipulation through `fetch_profile_surface` and related connectors.
- **ML‑experiment** enables reproducible training via `run_experiment` in [`loopx/capabilities/ml_experiment/runner.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/ml_experiment/runner.py).
- Invoke capabilities via `--capability-route` CLI flag or import Python modules directly.
- All actions are recorded in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) for auditability.

## Frequently Asked Questions

### How do I register a new capability in LoopX?

Register a new capability by adding a catalog entry to [`loopx/capabilities/catalog.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/catalog.py) with a unique ID, description, and documentation path. The entry must point to a valid package under `loopx/capabilities/` that follows the packet‑based architecture.

### Can I combine multiple capabilities in a single workflow?

Yes. Because capabilities exchange JSON‑serializable packets through the state projection system, you can chain them by passing output packets from one capability (e.g., `content_ops` surface data) as input to another (e.g., `ml_experiment` for analysis).

### Where are capability results stored for auditing?

All capability actions are automatically recorded in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py). This state‑projection system enables full replay, branching, and auditing of any workflow step without manual logging.

### What is the difference between packet builders and direct CLI invocation?

Packet builders like `build_issue_fix_feasibility_packet` are Python functions that construct validated data packets for programmatic use, while CLI invocation via `--capability-route` triggers the full command‑pack logic defined in [`loopx/cli_commands/ready_score.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/ready_score.py). Use packet builders for custom scripts and CLI routes for standard workflows.