Phy-Trace: Minimal Traceable Reasoning System

A minimal Python system for generating traceable structured reasoning steps as JSON nodes. Designed for AI agents to output machine-readable reasoning that can be validated and post-processed.

Purpose

• Generate traceable structured reasoning as JSON
• Validate reasoning structure (not mathematical correctness)
• Track dependencies between reasoning steps
• Manage definitions with version control
• Integrate seamlessly with AI agent tools

Quick Start

Prerequisite: Install uv

uv is a fast Python package installer and virtual environment manager.

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

For more info: https://docs.astral.sh/uv/getting-started/installation/

Install this Skill

Option 1: Install as an AI Skill (Recommended)

# Using bun
bunx skills add https://github.com/lvyuemeng/trace-reason

# Using npx
npx skills add https://github.com/lvyuemeng/trace-reason

Option 2: Clone and Install Locally

git clone https://github.com/yourusername/trace-reason

Quick Start

CLI Tool

# Process reasoning from input file
uv run python tools/cli.py input.json -o output.json --task "Prove complement property"

# Validate reasoning structure
uv run python tools/validate.py reasoning.json

How the CLI Works

The CLI tool processes input reasoning and generates structured output. Here's how it works:

Input Processing

1. Read Input: Takes JSON input with reasoning nodes
2. Validate Structure: Checks node IDs, dependencies, and format
3. Trace Reasoning: Follows dependency chains to ensure completeness
4. Generate Output: Produces validated JSON output

Command Structure

uv run python tools/cli.py [input.json] [options]

Common Options

• -o, --output: Output file path
• --task: Task description for context
• --definitions: Definitions file path
• --export-definitions: Export definitions to file

Example Workflow

# Step 1: Create input JSON with reasoning nodes
# Step 2: Process with CLI
uv run python tools/cli.py input.json -o output.json --task "Prove mathematical theorem"

# Step 3: Validate the output
uv run python tools/validate.py output.json

Validation

The validation tool checks:

• Node ID format compliance
• Missing references (warnings)
• Circular dependencies (warnings)
• Definition usage (warnings)

Note: Validation focuses on structural consistency, not mathematical correctness.

Node Schema

Every reasoning step is a JSON node:

{
  "node_id": "n1",
  "node_type": "Claim",
  "claim": "Natural language assertion",
  "depends_on": ["n0"],
  "uses_definition": ["definition name"],
  "requires_condition": ["assumption"]
}

Node Types

• Claim (n{num}): Primary assertion or conclusion
• Expand (e{num}): Decomposition of hidden reasoning
• Condition (c{num}): Assumption or prerequisite

Usage by AI Agents

Use:

{
  "task": "Prove complement of a finite-dimensional rectangle is a finite union of rectangles",
  "output_path": "reasoning.json"
}

Response (AI-generated):

{
  "nodes": [
    {
      "node_id": "n1",
      "node_type": "Claim",
      "claim": "Complement of a finite-dimensional rectangle is a finite union of rectangles.",
      "depends_on": [],
      "uses_definition": ["finite dimensional rectangle"],
      "requires_condition": ["finite dimension"]
    },
    {
      "node_id": "e1",
      "node_type": "Expand",
      "claim": "By definition, rectangle is a bounded set in \mathbb{R}^n",
      "depends_on": ["n1"],
      "uses_definition": ["finite dimensional rectangle", "bounded set"],
      "requires_condition": []
    }
  ]
}

License

MIT License

Contributing

Contributions are welcome! Please follow the existing code style and include tests for new features.

Philosophy

Minimal is better: Do not build graph DB, symbolic logic engine, constraint solver, type system, or category theory encoding. Focus on producing traceable reasoning logs. Additional features can be layered later.