LoopX API Documentation: A Complete Guide to the Python Public Interface

The LoopX API documentation is the official reference for the loopx Python package, exposing stable programmatic endpoints through modules like loopx/status.py, loopx/runtime.py, loopx/quota.py, and loopx/registry.py.

The LoopX API documentation defines how developers interact with the LoopX agent framework programmatically. Rather than a traditional REST API, LoopX provides a Python-native API surface through carefully curated modules that enforce a strict public-private boundary. This design ensures that all state mutations flow through validated control-plane logic, making the API both predictable and version-stable.

What the LoopX API Documentation Covers

The LoopX API documentation encompasses three interconnected sources: the auto-generated MkDocs site (built from mkdocs.yaml), the Markdown book under docs/book/en/chapters/, and inline docstrings in the source modules. Together, these document the four core API areas that external code should use.

Status and Observation (loopx/status.py)

Read-only access to LoopX state lives in loopx/status.py. The primary entry points are:

• get_status() – Returns a dictionary containing the current goal, active todos, quota consumption, and system health.
• observe() – Provides streaming or polling views of state changes.
• Status class – Typed container for structured access to system state.

These functions wrap the internal loopx/state_projection.py and loopx/state_refresh.py modules, ensuring callers cannot accidentally mutate state.

import loopx

# Query current LoopX state through the public API

status = loopx.status.get_status()
print("Current goal:", status["goal"])
print("Active todos:", len(status["todos"]))

Runtime and Goal Execution (loopx/runtime.py)

Goal lifecycle management resides in loopx/runtime.py. Key functions include:

• start_goal(name, config) – Creates and launches a new goal with validated configuration.
• run(task, args) – Executes a task within the current goal context.
• Runtime class – Lower-level interface for turn-by-turn agent loop processing.

This module is the primary entry point for driving LoopX programmatically. The same calls power the CLI commands loopx start-goal and loopx run.

import loopx

# Launch a new goal through the API

goal_cfg = {"description": "Run a data-clean-up pipeline", "priority": 5}
result = loopx.runtime.start_goal(
    name="optimize-data-pipeline",
    config=goal_cfg
)
print("Goal launched:", result["goal_id"])

Quota and Resource Gating (loopx/quota.py)

Capacity enforcement is handled by loopx/quota.py:

• check_quota(resource, amount) – Validates whether an operation can proceed without exceeding limits.
• Quota class – Structured access to quota policies and current consumption.

All resource-intensive operations should pre-check quota through this API.

import loopx

# Verify quota before expensive operations

if loopx.quota.check_quota(resource="cpu", amount=2):
    loopx.runtime.run(task="docker-build", args=["."])
else:
    print("Insufficient quota – defer the operation")

Extension Registry (loopx/registry.py)

Plugin discovery and installation are managed through loopx/registry.py:

• install_extension(spec) – Adds a new capability, provider, or host extension.
• list_extensions() – Enumerates registered extensions with version metadata.
• Registry class – Direct access to the extension loading system.

This API ensures extensions are properly validated and version-compatible before activation.

API Stability and Version Compatibility

The LoopX API documentation explicitly defines a stable compatibility range. As declared in docs/book/en/chapters/11-engineering-boundaries.md (line 27-30), extensions and user code must specify their required API version:

requires_loopx_api = ">=1,<2"

This semantic versioning guarantee means that code written against LoopX API 1.x will continue functioning across all 1.x releases. Breaking changes only occur at major version boundaries, with migration paths documented in the Markdown book chapters.

Where to Find LoopX API Documentation

Documentation Type	Location	Purpose
Auto-generated reference	Built from mkdocs.yaml	Searchable HTML docs with request/response schemas
Engineering design docs	docs/book/en/chapters/11-engineering-boundaries.md	API boundaries, compatibility rules, architectural rationale
Source docstrings	loopx/status.py, loopx/runtime.py, loopx/quota.py, loopx/registry.py	Exact function signatures, type hints, parameter descriptions
Quick-start examples	README.md	CLI-to-API mapping, common usage patterns

The MkDocs configuration in mkdocs.yaml orchestrates these sources into a unified documentation site, with the "Public API" chapter extracting callable signatures from the source modules.

Complete Working Example

import loopx

def run_optimized_pipeline():
    """Demonstrate the complete LoopX API surface."""
    
    # 1. Observe current state

    status = loopx.status.get_status()
    if status["goal"]:
        print(f"Already running: {status['goal']}")
        return
    
    # 2. Verify resources

    if not loopx.quota.check_quota(resource="memory_gb", amount=8):
        raise RuntimeError("Insufficient memory quota")
    
    # 3. Launch goal

    result = loopx.runtime.start_goal(
        name="data-optimization",
        config={"description": "ETL pipeline optimization", "priority": 5}
    )
    
    # 4. Execute tasks

    loopx.runtime.run(task="extract", args=["source-db"])
    loopx.runtime.run(task="transform", args=["normalize-schema"])
    loopx.runtime.run(task="load", args=["warehouse"])
    
    return result["goal_id"]

if __name__ == "__main__":
    run_optimized_pipeline()

This example exercises all four core API areas in a realistic workflow, matching the patterns used by the LoopX CLI internally.

Summary

• LoopX API documentation is delivered through the loopx Python package, not a REST endpoint.
• Four stable modules constitute the public surface: loopx/status.py (observation), loopx/runtime.py (execution), loopx/quota.py (gating), and loopx/registry.py (extensions).
• All state changes must pass through these APIs; direct mutation of internal loopx/state_* modules is prohibited by design.
• Version compatibility is explicitly declared via requires_loopx_api pins, with 1.x stability guaranteed.
• Documentation spans MkDocs-generated sites, Markdown book chapters, and source docstrings for comprehensive coverage.

Frequently Asked Questions

Where is the LoopX API documentation hosted?

The LoopX API documentation is built locally from the repository using MkDocs (mkdocs.yaml). There is no centralized hosted version; users generate the HTML reference from the docs/ directory. The source of truth remains the Python docstrings in loopx/status.py, loopx/runtime.py, and related modules.

How do I know if my code is using the stable LoopX API?

Check your imports. Stable API usage requires importing from top-level loopx submodules (loopx.status, loopx.runtime, etc.). Direct imports from loopx.state_projection, loopx.state_refresh, or other state_* modules indicate internal API usage that may break without notice.

What is the LoopX API version compatibility guarantee?

LoopX follows semantic versioning for its API surface. The requires_loopx_api = ">=1,<2" declaration in docs/book/en/chapters/11-engineering-boundaries.md confirms that all 1.x releases maintain backward compatibility. Extensions must declare their required range; the runtime validates this on load.

Can I use the LoopX API without the CLI?

Yes. The loopx CLI (loopx doctor, loopx start-goal) is a thin wrapper around the same Python API documented here. All CLI functionality is available programmatically through loopx.runtime.start_goal() and related functions, enabling headless automation and testing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}