Update Readme

[nezhyborets]

Introduce guide-based section like Text and prompting and others

What

This is a first step towards updating readme. The update will follow multiple guidelines.

Focus on "how to do it with our SDK" instead of "what it is"

Platforms become filled with information and we wouldn't be able to keep up. Let's leave explanations of concepts to guides and API reference, and link to them whenever needed. We could think of it in a way that OpenAI's guides and API Reference are sources of truth. They have all the instructions, explanations and example. We just have to cover the part they don't have: how to do it in Swift.

Use Guides as a reference for structuring

The idea here is that a lot of APIs share concepts, and taking API Reference instead of Guides as a reference could lead to a lot of duplication in our Readme.

The Guides have such a structure:

They cover concepts regardless of an endpoint a concept is applied to. We could do the same. Something like this:

Use Guides as a reference for contents

Each Guide has focus on the main stuff that would be required for a feature/concept to run. They also have good examples that highlight different aspects. We could follow their accents and examples closely, like "with our SDK you would do it like this ...". Like on the screenshots below - an example from Structured Outputs guide turned into an example of how to use JSONSchemaDefinition.jsonSchema in our code.

Focus on one side, but don't forget about another

A lot of things here have multiple sides:

1. Responses API vs Chat Completions API
2. Stream vs non-stream
3. Swift Concurrency, Combine, closures

If we'd cover all the sides in each section, we'd have to many text in the readme.

I'm thinking about going like this:

1. Show all examples on Responses API because it's the flagman, but provide Chat Completions API example in "collapsed" way because a lot of people still use it.
2. Show examples in sections in a non-streaming way, link to Streaming section wherever appropriate or feels necessary.
3. Show examples in sections only in Swift Concurrency. Create another section that would explain how to use Combine and Closures.

Why

Users seem to be having problems with our doc.
The file gets too big and hard to read and navigate.
To be able to keep up easier with the additions.

Affected Areas

README.md

[Krivoblotsky]

Thanks!