Devtu Code Optimization

ToolUniverse Code Optimization

Always run Skill(skill="simplify") after writing or modifying code.

Pre-Commit Checklist

• [ ] return_schema has oneOf: [{data+metadata}, {error}]
• [ ] Test examples use real IDs (no DUMMY/PLACEHOLDER)
• [ ] try: has except: at exact same indentation level
• [ ] No trailing commas in JSON (python3 -c "import json; json.load(open('f.json'))")
• [ ] New tool class registered in _lazy_registry_static.py and default_config.py
• [ ] ruff check src/tooluniverse/<file>.py passes
• [ ] python -c "from tooluniverse.<module> import <Class>" passes
• [ ] python -m tooluniverse.cli run <Tool> '<real_args_json>' returns expected data
• [ ] Ran Skill(skill="simplify") on all modified files

Key Fix Categories

References

• [references/api-fixes.md](references/api-fixes.md) — Per-API bug fixes (GtoPdb, CIViC, GTEx, ENCODE, CPIC, etc.)
• [references/code-patterns.md](references/code-patterns.md) — Reusable Python patterns (schema, filtering, pagination, normalization)

Git & PR Workflow

git fetch origin && git stash && git rebase origin/main && git stash pop
git push --force-with-lease origin fix/round-XX-bugs
gh pr view <N> --json mergeable  # must be MERGEABLE before done

• Never push to main directly
• Never have multiple open fix PRs
• Commit messages: "Feature" or "Fix" — never "Bug"
• No AI attribution in commits
• Repo: mims-harvard/ToolUniverse — verify with git remote -v

API-Specific Fix Reference

Patterns discovered through rounds 52–78 of role-play debugging.

Quick Lookup Table

Detailed Patterns

GtoPdb Gene Symbol Disambiguation (Feature-54B-001)

# Try precise geneSymbol first
gs_resp = request_with_retry(f"{base_url}/targets?geneSymbol={gene_symbol}")
if gs_resp.status_code == 200 and gs_resp.json():
    target_id = gs_resp.json()[0]["targetId"]
else:
    # Fall back to name (may return multiple)
    name_resp = request_with_retry(f"{base_url}/targets?name={gene_symbol}")
    ...

CIViC Fusion vs Mutation Regex (Feature-56A-001)

def _maybe_fuse(m):
    second = m.group(2)
    # Protein-change: single letter + digits + letter/asterisk (e.g. T790M, V600E)
    if re.match(r"^[A-Z]\d+[A-Z*]?$", second):
        return m.group(0)  # leave unchanged — it's a mutation
    return m.group(1) + "::" + second

normalized = re.sub(r"\b([A-Z][A-Z0-9]*)-([A-Z][A-Z0-9]+)\b", _maybe_fuse, mol_profile)

CPIC PostgREST Equality Filter (Feature-68A-004)

def _postgrest_eq(value):
    v = str(value)
    return v if v.startswith("eq.") else f"eq.{v}"

params["genesymbol"] = _postgrest_eq(gene_symbol)

ENCODE Assay Title Alias (Feature-73B)

ASSAY_ALIASES = {"ChIP-seq": "TF ChIP-seq", "CHIP": "TF ChIP-seq"}
assay_title = ASSAY_ALIASES.get(assay_title, assay_title)

GTEx Dataset Safety (Feature-69A-001)

dataset = arguments.get("dataset", "gtex_v8")
if dataset == "gtex_v10":
    result["dataset_note"] = "gtex_v10 may return empty; gtex_v8 is recommended."

Broken API Response

# Wrong: return stub success data
# Right:
return {
    "status": "error",
    "message": "HMDB has no public REST API. Use MetabolomicsWorkbench or ChEBI instead."
}

Code Patterns Reference

Reusable implementation patterns for ToolUniverse tool development.

Schema Patterns

return_schema with oneOf (required)

{
  "return_schema": {
    "oneOf": [
      {
        "type": "object",
        "properties": {
          "data": {"type": "object"},
          "metadata": {"type": "object"}
        }
      },
      {
        "type": "object",
        "properties": {
          "error": {"type": "string"}
        }
      }
    ]
  }
}

Nullable fields

{"type": ["array", "null"]}
{"type": ["string", "null"]}

API Call Patterns

Client-Side Filter (when API ignores params)

results = api_call(base_params_only)
if interaction_types:
    results = [r for r in results if r.get("type") in interaction_types]
if sources:
    results = [r for r in results if r.get("source") in sources]

Fallback Lookup

precise = api_call(geneSymbol=gene_symbol)
if not precise:
    precise = api_call(name=gene_symbol)

Client-Side Pagination (when API ignores size/page)

all_items = api_call()
start = page * size
return all_items[start:start + size]

PostgREST Join

url = f"{base}/recommendation?select=*,drug(name)&genesymbol={_postgrest_eq(gene)}"

Output Patterns

Normalization Disclosure

_norm_parts = []
if original != normalized:
    _norm_parts.append(f"'{original}' → '{normalized}' (reason)")
if _norm_parts:
    result["normalization_note"] = "Auto-normalized: " + "; ".join(_norm_parts)

Truncation at Top Level

response = {"status": "success", "data": data[:limit]}
if len(data) > limit:
    response["truncated"] = True
    response["truncation_note"] = (
        f"Returning {limit} of {len(data)}. "
        f"Pass max_results={len(data)} for full data."
    )

No-Data vs Bad-Query

if count == 0 and query:
    result["hint"] = f"No results for '{query}'. Try a broader term or check spelling."
elif count == 0:
    result["hint"] = "No data available for this entity."

try/except Indentation (Critical)

# CORRECT
try:
    resp = requests.get(url)
    data = resp.json()
except Exception as e:
    return {"status": "error", "error": str(e)}

# WRONG — SyntaxError
try:
    resp = requests.get(url)
if resp.ok:        # ← same indent as try: → OUTSIDE try block
    data = resp.json()
except Exception:  # ← Python: "try without except"
    pass

Every try: must have except: at the exact same indentation level.

Multi-Word Search Hint

if result["count"] == 0 and name_q and " " in str(name_q):
    first_word = str(name_q).split()[0]
    result["multi_word_hint"] = (
        f"Search may not match multi-word phrases like '{name_q}'. "
        f"Try a single keyword: name='{first_word}'."
    )