Show HN: Sosumi.ai – Convert Apple Developer docs to AI-readable Markdown (opens in new tab)

Jim Reekes talking about this in a deleted scene from the documentary Welcome to Macintosh: https://www.youtube.com/watch?v=k4J8AF25PjA

There's also a episode on https://www.macintosh.fm about the topic that I can recommend.

When I was a kid I used Sosumi as my chime on the apple IIGS!

> why are we focussing on making things accessible to AI

Because that’s the authors actual goal? To take a web page that looks fine to human eyes but is unintuitively not accessible to AI. That’s genuinely useful and valuable.

Sure it’s no different than converting it to markdown for human eyes. But it’s important to be clear about not just WHAT but also WHY.

C’mon now. This isn’t controversial or even bad.

Thanks for pointing that out. That’s most likely a mistake in how I’m translating into Markdown. I’ll look into this.

I think HTML -> Markdown is a bit of a red herring.

In many cases, a Markdown distillation of HTML can improve the signal-to-noise ratio — especially for sites mired in <div> tag soup (intentionally or not). But that's an optimization for token efficiency; LLMs can usually figure things out.

The motivation behind Sosumi is better understood as a matter of accessibility. The way AI assistants typically fetch content from the web precluded them from getting any useful information from developer.apple.com.

You could start to solve the generalized problem with an MCP that 1) used a headless browser to access content for sites that require JS, and 2) used sampling (i.e. having a tool use the host LLM) to summarize / distill HTML.

https://pure.md is exactly what you're looking for.

But stripping complex formats like html & pdf down to simple markdown is a hard problem. It's nearly impossible to infer what the rendered page looks like by looking at the raw html / pdf code. https://github.com/mozilla/readability helps but it often breaks down over unconventional div structures. I heard the state of the art solution is using multimodal LLM OCR to really look at the rendered page and rewrite the thing in markdown.

Which makes me wonder: how did OpenAI make their model read pdf, docx and images at all?

There are APIs such as Jina AI's reader API that do this pretty well. It doesn't produce output as clean as Sosumi for Apple docs, but it's free and does a decent job.

https://jina.ai/reader

This is only possible for some of Apple‘s open source Swift code, including the Swift standard library. This is not the case for hundreds of other SDK frameworks, such as SwiftUI.

Even for those open source projects, there is still some value added in the generated documentation that isn’t directly available from documentation comments, such as type members and protocol conformances (though a LLM could certainly suss that out with the right context).

Great idea! I just added that. Try clicking the icon in the header.

In my experience, coding agents seem to do a normal fetch when provided links. Which makes sense — headless browser automation is expensive, and only really necessary for interacting with a webpage.

But with these RLHF'd AIs, being confident and helpful as they are, it took me a while to realize that they couldn't actually read the Apple developer links I was giving them. Like a kid who can't read the chalkboard, but doesn't realize they need glasses.

Understand yes but the issue that this project is built for is to access data

Once upon a time, I built a project called `swift-doc`, which eventually got Sherlocked. I think what I was most upset about was their decision to call their thing "DocC". Like, adding redundant consonants to avoid name collisions is my shtick.

Long live Jazzy.

Sure, here are a few more examples:

- https://developer.apple.com/documentation/swift/tasklocal

- https://sosumi.ai/documentation/swiftui/button

- https://sosumi.ai/documentation/foundation/measurement

Most of the docs about the language itself live on swift.org (e.g. https://docs.swift.org/swift-book/documentation/the-swift-pr...). I've had pretty good luck getting Claude to write modern Swift code by saying things like "Use Swift 6 structured concurrency instead of GCD". But I could totally see expanding sosumi to include swift.org content, too.

Edit: Another Swift developer life hack: for new language features, copy-pasting the Swift Evolution proposal works pretty well! https://github.com/swiftlang/swift-evolution/tree/main/propo...

Hi Saagar! One could indeed use this method to export this information en-masse, however that would require the kind of automated access that the site ToS explicitly forbids.

For the Swift standard library and other open-source frameworks, you could probably extract this from documentation comments using DocC, Jazzy, or the like.

I agree, it'd be great if Apple provided accessible documentation in the first place. Time was, Apple published self-contained docsets that you could download and read offline.

Apple's ToS pretty explicitly forbid the kind of automation required to download everything. But even if someone did that, it'd only be a snapshot in time. And a lot can can change between OS releases.

As for the hosted web app, I wanted to provide this as a public service. I plan to open source it, so anyone can self-host instead, if they're inclined.

The AI only sees a bit of HTML plus a bunch of JS that, when executed, generates more HTML. If the AI does not run the JS it won’t see everything. During training they probably use a crawler that runs a headless browser behind the scenes to get everything a human would get.

Ai can’t read something dynamically rendered with JavaScript. At the moment.

They can, but the token to content ratio is far less, so they work less effectively when it's put into the inference context window.

Not yet, but I plan to open source it soon. Just gotta tidy up a little bit, you know?

I remember copilot with GPT helping me export Swift to C for interop. Something I could hardly find good examples and info on in my google searches.

ChatGPT does swift and objc remarkably well including UIKit and core data. Its gotten much better for project files with gpt5-mini

Is it open source?

Amen to that. It's funny how virtues like accessibility and good API design matter just as much as ever in this new era. Good ideas don't go out of style.