Get library overview and entry points #16

New issue

Open

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

mprihoda commented

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

(Migrated from github.com)

Problem

Agent encounters an unfamiliar library and needs to quickly understand:

What is this library for?
What are the main concepts?
Where do I start?

Reading full docs for every class is too slow and token-expensive.

Proposed Solution

New Tool: `get_library_overview`

{
  "name": "get_library_overview",
  "description": "Get high-level overview of a library",
  "input": {
    "coordinates": "Maven/Coursier coordinates",
    "scalaVersion": "optional"
  }
}

Example:

get_library_overview("org.typelevel::cats-effect:3.5.4")

Returns:

## cats-effect 3.5.4

**Purpose:** Purely functional runtime system for Scala with async/concurrent primitives.

**Core Concepts:**
- **IO[A]** - Primary effect type representing suspended computation
- **Resource[F, A]** - Safe resource acquisition and release
- **Fiber[F, E, A]** - Lightweight thread for concurrent execution

**Entry Points:**
- `IOApp` - Trait for main application
- `IO.delay` / `IO.pure` - Create effects
- `Resource.make` - Create managed resources

**Main Packages:**
- `cats.effect` - Core types (IO, Resource, Fiber)
- `cats.effect.std` - Standard utilities (Queue, Semaphore)
- `cats.effect.kernel` - Typeclasses (Async, Concurrent)

**Common Patterns:**
- Wrap side effects with `IO.delay(...)`
- Use `Resource` for anything needing cleanup
- Compose with `for` comprehensions

**Related Libraries:**
- cats-core (Functor, Monad, etc.)
- fs2 (streaming)
- http4s (HTTP)

Implementation

Fetch README from Maven Central or GitHub
Parse package-summary.html for structure
Use AI summarization for README content
Cache overviews (expensive to generate)

Value for Agent

30-second understanding of any library
Know where to start without guessing
Understand how pieces fit together

Acceptance Criteria

Generate coherent overview for major libraries (cats-effect, ZIO, tapir)
Identify entry point classes
List main packages with purposes
Keep response under 1000 tokens

## Problem Agent encounters an unfamiliar library and needs to quickly understand: - What is this library for? - What are the main concepts? - Where do I start? Reading full docs for every class is too slow and token-expensive. ## Proposed Solution ### New Tool: `get_library_overview` ```json { "name": "get_library_overview", "description": "Get high-level overview of a library", "input": { "coordinates": "Maven/Coursier coordinates", "scalaVersion": "optional" } } ``` **Example:** ``` get_library_overview("org.typelevel::cats-effect:3.5.4") ``` **Returns:** ```markdown ## cats-effect 3.5.4 **Purpose:** Purely functional runtime system for Scala with async/concurrent primitives. **Core Concepts:** - **IO[A]** - Primary effect type representing suspended computation - **Resource[F, A]** - Safe resource acquisition and release - **Fiber[F, E, A]** - Lightweight thread for concurrent execution **Entry Points:** - `IOApp` - Trait for main application - `IO.delay` / `IO.pure` - Create effects - `Resource.make` - Create managed resources **Main Packages:** - `cats.effect` - Core types (IO, Resource, Fiber) - `cats.effect.std` - Standard utilities (Queue, Semaphore) - `cats.effect.kernel` - Typeclasses (Async, Concurrent) **Common Patterns:** - Wrap side effects with `IO.delay(...)` - Use `Resource` for anything needing cleanup - Compose with `for` comprehensions **Related Libraries:** - cats-core (Functor, Monad, etc.) - fs2 (streaming) - http4s (HTTP) ``` ## Implementation - Fetch README from Maven Central or GitHub - Parse package-summary.html for structure - Use AI summarization for README content - Cache overviews (expensive to generate) ## Value for Agent - 30-second understanding of any library - Know where to start without guessing - Understand how pieces fit together ## Acceptance Criteria - [ ] Generate coherent overview for major libraries (cats-effect, ZIO, tapir) - [ ] Identify entry point classes - [ ] List main packages with purposes - [ ] Keep response under 1000 tokens