docs(providers): rewrite OpenAI / Anthropic / Ollama / OCI pages#27
Merged
Conversation
The previous provider pages were correct but terse — capability tree
dumps with no narrative, weak "when to pick" guidance, and no
practical-workflow worked examples. This rewrite restructures every
page around the same easy-to-read template:
1. One-paragraph "what this provider is + why you'd pick it"
2. "When to pick X" table with cross-links to alternatives
3. Getting started — three numbered steps
4. What you get out of the box — each capability as natural prose
plus a runnable code example, not a single-line bullet
5. Practical workflow / gotcha section
6. Common gotchas table
7. Source links + See also
Per-page highlights
-------------------
- OpenAI: separated chat / o-series reasoning / streaming /
tool-calling / structured-output as their own subsections; gateway
tour (Azure / Portkey / LiteLLM / vLLM / together) explains when
each one is the right pick.
- Anthropic: the prompt-caching cost story spelled out (1/10× input
on cached span; ~5-min ephemeral window; auto when system >
~1024 tokens). Extended-thinking ThinkEvent example. Cross-link to
Claude-on-OCI as a no-API-key alternative.
- Ollama: positioned as "develop offline / test deterministically /
iterate before paying"; per-model tool-calling support table; the
laptop→hosted swap-one-line workflow demonstrated.
- OCI: now leads with the value prop ("90+ models, day-0 model
coverage, one auth surface"). Three-transport story (V1 / SDK /
DAC) with a single ascii table showing routing by model-id
pattern. DAC section integrates the new how-to. The "laptop dev →
OKE production" workflow shows the value of one auth surface
concretely.
Page sizes: 318 → 719 lines total.
- openai: 78 → 165
- anthropic: 71 → 186
- ollama: 73 → 167
- oci: 97 → 201
Validation
----------
- ``hatch run check`` clean.
- ``mkdocs build --strict`` not re-run here; docs.yml CI workflow
catches link rot on the next push to main.
Signed-off-by: Federico Kamelhar <federico.kamelhar@oracle.com>
oracle-contributor-agreement
Bot
added
the
OCA Verified
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The previous provider pages were correct but terse — capability tree dumps, weak "when to pick" guidance, no practical-workflow worked examples. This rewrite restructures every page around the same easy-to-read template:
Per-page highlights
ThinkEventexample. Cross-link to Claude-on-OCI as a no-API-key alternative.Page sizes
More substance, but structured so each section is short and skimmable. Headers carry the story; every code block is runnable.
Validation
hatch run checkclean.Test plan
mkdocs build --strictruns indocs.ymlworkflow on next main push (catches dead links).CI Successpasses.