docs: rewrite README for first-time user experience#66
Conversation
- Add installation section with SPM + Xcode instructions - Make Swift 6 package traits prominent and unavoidable - Lead with @generable structured output as the superpower - Add tool calling teaser with real Swift code - Add SwiftUI ChatSession drop-in example - Show side-by-side provider swap (cloud/MLX/Ollama) - Replace decorative SVG with real performance table - Fix API mismatches (AnthropicProvider, model IDs, Ollama init) - Add Linux/server-side guidance
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9438ed1537
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| </p> | ||
| <p align="center"><i>Benchmark: Token throughput on M3 Max (Llama 3.1 8B, 4-bit Quantized)</i></p> | ||
| ```bash | ||
| swift package add --url https://github.com/christopherkarani/Conduit --from 0.3.0 |
There was a problem hiding this comment.
On SwiftPM 6.2, swift package --help lists add-dependency, and swift package add-dependency --help shows the syntax swift package add-dependency <dependency> ... [--from <from>]; there is no add subcommand or --url option. This makes the first install command fail for new users, so it should use the supported add-dependency https://github.com/christopherkarani/Conduit --from 0.3.0 form or show the Package.swift dependency directly.
Useful? React with 👍 / 👎.
| let result = try await provider.generate( | ||
| messages: Messages { Message.user("Review the movie Inception") }, | ||
| model: .claudeSonnet45, | ||
| config: .default.responseFormat(.jsonSchema(MovieReview.generationSchema)) |
There was a problem hiding this comment.
ResponseFormat only defines case jsonSchema(name: String, schema: GenerationSchema) in GenerateConfig.swift, so .jsonSchema(MovieReview.generationSchema) does not compile because the name: and schema: labels are required. Readers copying the structured-output quick start will hit this before they can run the example; use the labeled form shown elsewhere in the API docs.
Useful? React with 👍 / 👎.
| let result = try await provider.generate( | ||
| messages: Messages { Message.user("What's the weather in Tokyo?") }, | ||
| model: .claudeSonnet45, | ||
| config: .default.tools([WeatherTool()]) |
There was a problem hiding this comment.
Passing .tools([WeatherTool()]) to provider.generate only sends tool definitions; GenerationResult.toolCalls documents that callers must execute the requested tools and send the outputs in a follow-up request, while ChatSession only automates this when a ToolExecutor is configured. In this README flow the model can request get_weather, but WeatherTool.call is never invoked, so the example does not actually let the model call the Swift function.
Useful? React with 👍 / 👎.
| let local = Conduit(.mlx()) | ||
| let localSession = try local.session(model: .mlxLocal("/Users/me/models/Llama-3.2-1B-Instruct-4bit")) | ||
| // Local via Ollama | ||
| let ollama = OpenAIProvider(ollamaHost: "localhost", port: 11434) |
There was a problem hiding this comment.
OpenAIProvider exposes init(apiKey:), init(endpoint:apiKey:), and init(configuration:), and Ollama is selected through OpenAIEndpoint.ollama(host:port:); there is no OpenAIProvider(ollamaHost:port:) initializer. This provider-swap snippet will not compile for users copying it, so it should be OpenAIProvider(endpoint: .ollama(host: "localhost", port: 11434)).
Useful? React with 👍 / 👎.
christopherkarani
deleted the
codex/conduit-foundationmodels-provider-expansion
branch
1 participant
Summary
Complete rewrite of the README from a first-time-user perspective. Evaluated the old README at 3/10 for new-user onboarding; this rewrite targets a 9/10.
What changed
swift package addcommand + Xcode UI instructions@Generablestructured output is now the hero example (previously hidden in a docs link)Toolprotocol +@Generablearguments snippetChatSessiondrops directly into aViewAnthropicProvider(apiKey:)matches actual API; fixed model IDs;OpenAIProvider(ollamaHost:port:)matches sourceWhy the old README failed new users
Conduit(.anthropic(...))wrapper API didn't exist — confused the mental model@Generable) was completely absent from the landing pageChecklist