Search by return type (simplified Hoogle) #17

New issue

Open

opened 2026-01-05 21:14:31 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 21:14:31 +00:00

(Migrated from github.com)

Problem

Agent knows what type it has and what type it needs, but doesn't know which method bridges them:

"I have a List[A], I need an Option[A]"
"I have an IO[Option[A]], I need an OptionT[IO, A]"
"I have a String, I need a URI"

Proposed Solution

New Tool: `search_by_type`

Start with simplified return-type search, evolve toward full Hoogle-style.

{
  "name": "search_by_type",
  "description": "Find methods by type signature",
  "input": {
    "coordinates": "Maven/Coursier coordinates", 
    "returnType": "Type to search for",
    "inputType": "optional, type of input parameter",
    "scalaVersion": "optional"
  }
}

Example queries:

search_by_type("org.typelevel::cats-effect:3.5.4", returnType="Resource[F, A]")
search_by_type("org.typelevel::cats-core:2.10.0", returnType="Option[A]", inputType="List[A]")

Returns:

{
  "matches": [
    {
      "method": "Resource.make[F[_], A](acquire: F[A])(release: A => F[Unit])",
      "class": "cats.effect.kernel.Resource",
      "description": "Creates a resource from acquire and release actions"
    },
    {
      "method": "Resource.pure[F[_], A](a: A)",
      "class": "cats.effect.kernel.Resource",
      "description": "Lifts a pure value into Resource"
    }
  ]
}

Implementation Phases

Phase 1: Return type only

Index method return types from TASTy/Scaladoc
Exact match + subtype match

Phase 2: Input → Output

Match methods where input type appears in parameters
Handle curried functions

Phase 3: Full Hoogle

Polymorphic matching (type variables)
Fuzzy matching (similar types)
Rank by relevance

Technical Approach

Use TASTy for Scala 3 artifacts (has full type info)
Parse Javadoc method signatures for Java
Build searchable index per artifact
Cache indexes

Value for Agent

"How do I get from A to B?" answered directly
Discovers methods without reading all docs
Finds factory methods, conversions, etc.

Acceptance Criteria

Phase 1: Search by return type
Match exact types and subtypes
Return method signature + class + description
Work for both companion object methods and instance methods

## Problem Agent knows what type it has and what type it needs, but doesn't know which method bridges them: - "I have a `List[A]`, I need an `Option[A]`" - "I have an `IO[Option[A]]`, I need an `OptionT[IO, A]`" - "I have a `String`, I need a `URI`" ## Proposed Solution ### New Tool: `search_by_type` Start with simplified return-type search, evolve toward full Hoogle-style. ```json { "name": "search_by_type", "description": "Find methods by type signature", "input": { "coordinates": "Maven/Coursier coordinates", "returnType": "Type to search for", "inputType": "optional, type of input parameter", "scalaVersion": "optional" } } ``` **Example queries:** ``` search_by_type("org.typelevel::cats-effect:3.5.4", returnType="Resource[F, A]") search_by_type("org.typelevel::cats-core:2.10.0", returnType="Option[A]", inputType="List[A]") ``` **Returns:** ```json { "matches": [ { "method": "Resource.make[F[_], A](acquire: F[A])(release: A => F[Unit])", "class": "cats.effect.kernel.Resource", "description": "Creates a resource from acquire and release actions" }, { "method": "Resource.pure[F[_], A](a: A)", "class": "cats.effect.kernel.Resource", "description": "Lifts a pure value into Resource" } ] } ``` ## Implementation Phases **Phase 1:** Return type only - Index method return types from TASTy/Scaladoc - Exact match + subtype match **Phase 2:** Input → Output - Match methods where input type appears in parameters - Handle curried functions **Phase 3:** Full Hoogle - Polymorphic matching (type variables) - Fuzzy matching (similar types) - Rank by relevance ## Technical Approach - Use TASTy for Scala 3 artifacts (has full type info) - Parse Javadoc method signatures for Java - Build searchable index per artifact - Cache indexes ## Value for Agent - "How do I get from A to B?" answered directly - Discovers methods without reading all docs - Finds factory methods, conversions, etc. ## Acceptance Criteria - [ ] Phase 1: Search by return type - [ ] Match exact types and subtypes - [ ] Return method signature + class + description - [ ] Work for both companion object methods and instance methods