{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"sdks-versus-raw-requests","title":"A provider's SDK: what it does for you, what it hides, and how to read it","url":"https://addaly.com/learn/python-for-ai/sdks-versus-raw-requests","position":54,"of":89,"minutes":8,"answer":"An SDK is a Session with the auth header, retries, typed responses and streaming already written; the same OpenAI-shaped client talks to a free local model by changing base_url.","keyIdea":"An SDK is a Session with the auth header, retries, typed responses and streaming already written; the same OpenAI-shaped client talks to a free local model by changing base_url, and when it misbehaves the source is sitting in your virtual environment to read."},"body":{"format":"markdown","text":"## Two ways to make the same call\n\nWith `requests`:\n\n```python\nr = session.post(\n    \"https://api.openai.com/v1/chat/completions\",\n    headers={\"Authorization\": f\"Bearer {key}\"},\n    json={\"model\": \"gpt-4o-mini\", \"messages\": [{\"role\": \"user\", \"content\": \"Hi\"}]},\n    timeout=(5, 120),\n)\nr.raise_for_status()\ntext = r.json()[\"choices\"][0][\"message\"][\"content\"]\n```\n\nWith the provider's SDK:\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI()          # reads OPENAI_API_KEY from the environment\nresp = client.chat.completions.create(\n    model=\"gpt-4o-mini\",\n    messages=[{\"role\": \"user\", \"content\": \"Hi\"}],\n)\ntext = resp.choices[0].message.content\n```\n\nThe second is shorter, and it is worth being exact about what the shortness bought.\n\n## What the SDK does for you\n\n**The session and the headers.** The client object is a persistent HTTP client (`httpx` underneath) with keep-alive, the auth header, the API version header and a `User-Agent`, set once.\n\n**Retries.** Two attempts with exponential backoff on 408, 409, 429 and 5xx, honouring `Retry-After`. You saw last lesson why you should not wrap this in your own loop.\n\n**Typed responses.** `resp.choices[0].message.content` is attribute access on an object, so a typo raises `AttributeError` at that line with the name in it, and your editor can autocomplete the fields. With a raw dict a typo raises `KeyError` and the editor knows nothing.\n\n**Errors as exception classes.** A 401 becomes `AuthenticationError`, a 429 becomes `RateLimitError`, a 400 becomes `BadRequestError`, each with the server's message attached. `except RateLimitError:` reads better than `if r.status_code == 429:`.\n\n**Streaming, files, tools.** Each is a parameter or a method rather than a protocol you implement.\n\n**Keeping up.** When the provider adds a field, the SDK gains it in the next release. With `requests` you read the changelog yourself.\n\n## What it hides\n\n**Which URL and which version.** The SDK knows the endpoint; you do not see it. When a request fails in a way the error message does not explain, you need to see the bytes that went out, and the SDK's abstraction is in the way. Every SDK has a way through: set `OPENAI_LOG=debug` or, for Anthropic, `ANTHROPIC_LOG=debug`, and the client prints each request and response.\n\n**Timeouts.** The `openai` client defaults to 600 seconds. That is ten minutes of silent waiting if something wedges. Set it: `OpenAI(timeout=60.0)`, or per call with `client.with_options(timeout=30).chat...`.\n\n**Dependency weight.** The `anthropic` package pulls in `httpx`, `pydantic`, `anyio`, `typing-extensions` and more. On a phone under Termux or a machine with a slow connection this is not nothing. `requests` is one small package.\n\n**Its own bugs.** SDKs are code; they have versions and regressions. Pin them like anything else.\n\n## One shape, many servers\n\nHere is the fact that matters most for a learner without a card to put on a paid account. The OpenAI request and response format has become a de facto standard, and free servers speak it.\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(base_url=\"http://localhost:11434/v1\", api_key=\"ollama\")\nresp = client.chat.completions.create(\n    model=\"llama3.2\",\n    messages=[{\"role\": \"user\", \"content\": \"Hi\"}],\n)\n```\n\nThat is the same SDK talking to Ollama running a free model on your own laptop. `api_key` must be non-empty because the client insists; Ollama ignores it. The same trick works for `llama.cpp`'s server, LM Studio, vLLM, and most hosted providers of open models. Code written against the OpenAI shape can move between a free local model for development and a paid one for production by changing two strings.\n\nAnthropic's format is different: `messages.create` returns `content` as a list of blocks, so code written against one SDK does not run against the other. If you may need to switch, keep the call in one function of your own and let only that function know which SDK it is using. Module 7 turns that into a class.\n\n## Reading the SDK\n\nThe single most useful habit with any library: find it and read it.\n\n```python\nimport openai\nprint(openai.__file__)\n# .../.venv/lib/python3.12/site-packages/openai/__init__.py\n```\n\nOpen that folder. `_client.py` is the client, `_base_client.py` has the retry loop with its backoff constants, and `resources/chat/completions.py` is where `create` lives, with every parameter documented in the signature. When the documentation site is vague about a default, the code is not.\n\n`help(client.chat.completions.create)` in the shell prints the docstring without leaving the terminal. `inspect.signature(...)` prints the parameters and defaults.\n\n## Which to use\n\nUse the SDK when one exists and the provider is your main dependency. Use `requests` when the provider has no SDK, when the SDK is heavier than your whole program, when you need to see exactly what is sent, or when you are teaching yourself what an SDK does, which is what the first two lessons of this module were for.\n\nWhichever you use, construct the client once. A new `OpenAI()` inside a function called in a loop throws away the session each time and reintroduces every handshake you learned to avoid.\n\n## Try this now\n\nInstall Ollama (free, runs on CPU), pull a small model with `ollama pull qwen2.5:0.5b`, and run the `base_url` example with `model=\"qwen2.5:0.5b\"`. Then set `OPENAI_LOG=debug` and run it again to see the request the SDK actually sent."},"check":{"question":"A developer's script using the `openai` package works against OpenAI's API. They change only `base_url=\"http://localhost:11434/v1\"` and `model=\"llama3.2\"` to point it at Ollama running on their laptop, and it works too. What makes this possible?","options":[{"text":"The `openai` package detects a localhost address and switches to a built-in local inference engine.","correct":false,"tempting":"The package contains no model; it is an HTTP client, and it has no special handling for localhost."},{"text":"Ollama serves an HTTP endpoint that accepts OpenAI's request shape and returns its response shape, so the client code needs no change.","correct":true},{"text":"The SDK proxies the request to OpenAI and forwards the answer to the local server, which caches it so that later identical prompts are answered locally without a second round trip.","correct":false,"tempting":"Nothing goes to OpenAI; the request travels only to the URL you configured, which is the whole point of `base_url`."},{"text":"Both services share a Python package, so the client imports Ollama's code when it sees the model name.","correct":false,"tempting":"There is no shared package; the compatibility lives in the HTTP request and response format, not in Python."}]},"prev":{"slug":"pagination-and-cursors","title":"Pagination: walking a result that arrives in pages","url":"https://addaly.com/learn/python-for-ai/pagination-and-cursors"},"next":{"slug":"consuming-a-stream","title":"Consuming a streamed reply: server-sent events, line by line","url":"https://addaly.com/learn/python-for-ai/consuming-a-stream"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'A provider's SDK: what it does for you, what it hides, and how to read it', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/sdks-versus-raw-requests (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"A provider’s SDK: what it does for you, what it hides, and how to read it","courseTitle":"Python, from Zero, for AI","module":{"index":6,"slug":"talking-to-a-service","title":"Talking to a service: HTTP from Python, done properly"},"answer":null,"keyIdea":"An SDK is a Session with the auth header, retries, typed responses and streaming already written; the same OpenAI-shaped client talks to a free local model by changing base_url, and when it misbehaves the source is sitting in your virtual environment to read.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"two-ways-to-make-the-same-call","runs":[{"text":"Two ways to make the same call"}]},{"t":"p","runs":[{"text":"With "},{"text":"requests","code":true},{"text":":"}]},{"t":"code","lang":"python","label":"Python","text":"r = session.post(\n    \"https://api.openai.com/v1/chat/completions\",\n    headers={\"Authorization\": f\"Bearer {key}\"},\n    json={\"model\": \"gpt-4o-mini\", \"messages\": [{\"role\": \"user\", \"content\": \"Hi\"}]},\n    timeout=(5, 120),\n)\nr.raise_for_status()\ntext = r.json()[\"choices\"][0][\"message\"][\"content\"]"},{"t":"p","runs":[{"text":"With the provider’s SDK:"}]},{"t":"code","lang":"python","label":"Python","text":"from openai import OpenAI\n\nclient = OpenAI()          # reads OPENAI_API_KEY from the environment\nresp = client.chat.completions.create(\n    model=\"gpt-4o-mini\",\n    messages=[{\"role\": \"user\", \"content\": \"Hi\"}],\n)\ntext = resp.choices[0].message.content"},{"t":"p","runs":[{"text":"The second is shorter, and it is worth being exact about what the shortness bought."}]},{"t":"h2","id":"what-the-sdk-does-for-you","runs":[{"text":"What the SDK does for you"}]},{"t":"p","runs":[{"text":"The session and the headers.","b":true},{"text":" The client object is a persistent HTTP client ("},{"text":"httpx","code":true},{"text":" underneath) with keep-alive, the auth header, the API version header and a "},{"text":"User-Agent","code":true},{"text":", set once."}]},{"t":"p","runs":[{"text":"Retries.","b":true},{"text":" Two attempts with exponential backoff on 408, 409, 429 and 5xx, honouring "},{"text":"Retry-After","code":true},{"text":". You saw last lesson why you should not wrap this in your own loop."}]},{"t":"p","runs":[{"text":"Typed responses.","b":true},{"text":" "},{"text":"resp.choices[0].message.content","code":true},{"text":" is attribute access on an object, so a typo raises "},{"text":"AttributeError","code":true},{"text":" at that line with the name in it, and your editor can autocomplete the fields. With a raw dict a typo raises "},{"text":"KeyError","code":true},{"text":" and the editor knows nothing."}]},{"t":"p","runs":[{"text":"Errors as exception classes.","b":true},{"text":" A 401 becomes "},{"text":"AuthenticationError","code":true},{"text":", a 429 becomes "},{"text":"RateLimitError","code":true},{"text":", a 400 becomes "},{"text":"BadRequestError","code":true},{"text":", each with the server’s message attached. "},{"text":"except RateLimitError:","code":true},{"text":" reads better than "},{"text":"if r.status_code == 429:","code":true},{"text":"."}]},{"t":"p","runs":[{"text":"Streaming, files, tools.","b":true},{"text":" Each is a parameter or a method rather than a protocol you implement."}]},{"t":"p","runs":[{"text":"Keeping up.","b":true},{"text":" When the provider adds a field, the SDK gains it in the next release. With "},{"text":"requests","code":true},{"text":" you read the changelog yourself."}]},{"t":"h2","id":"what-it-hides","runs":[{"text":"What it hides"}]},{"t":"p","runs":[{"text":"Which URL and which version.","b":true},{"text":" The SDK knows the endpoint; you do not see it. When a request fails in a way the error message does not explain, you need to see the bytes that went out, and the SDK’s abstraction is in the way. Every SDK has a way through: set "},{"text":"OPENAI_LOG=debug","code":true},{"text":" or, for Anthropic, "},{"text":"ANTHROPIC_LOG=debug","code":true},{"text":", and the client prints each request and response."}]},{"t":"p","runs":[{"text":"Timeouts.","b":true},{"text":" The "},{"text":"openai","code":true},{"text":" client defaults to 600 seconds. That is ten minutes of silent waiting if something wedges. Set it: "},{"text":"OpenAI(timeout=60.0)","code":true},{"text":", or per call with "},{"text":"client.with_options(timeout=30).chat...","code":true},{"text":"."}]},{"t":"p","runs":[{"text":"Dependency weight.","b":true},{"text":" The "},{"text":"anthropic","code":true},{"text":" package pulls in "},{"text":"httpx","code":true},{"text":", "},{"text":"pydantic","code":true},{"text":", "},{"text":"anyio","code":true},{"text":", "},{"text":"typing-extensions","code":true},{"text":" and more. On a phone under Termux or a machine with a slow connection this is not nothing. "},{"text":"requests","code":true},{"text":" is one small package."}]},{"t":"p","runs":[{"text":"Its own bugs.","b":true},{"text":" SDKs are code; they have versions and regressions. Pin them like anything else."}]},{"t":"h2","id":"one-shape-many-servers","runs":[{"text":"One shape, many servers"}]},{"t":"p","runs":[{"text":"Here is the fact that matters most for a learner without a card to put on a paid account. The OpenAI request and response format has become a de facto standard, and free servers speak it."}]},{"t":"code","lang":"python","label":"Python","text":"from openai import OpenAI\n\nclient = OpenAI(base_url=\"http://localhost:11434/v1\", api_key=\"ollama\")\nresp = client.chat.completions.create(\n    model=\"llama3.2\",\n    messages=[{\"role\": \"user\", \"content\": \"Hi\"}],\n)"},{"t":"p","runs":[{"text":"That is the same SDK talking to Ollama running a free model on your own laptop. "},{"text":"api_key","code":true},{"text":" must be non-empty because the client insists; Ollama ignores it. The same trick works for "},{"text":"llama.cpp","code":true},{"text":"’s server, LM Studio, vLLM, and most hosted providers of open models. Code written against the OpenAI shape can move between a free local model for development and a paid one for production by changing two strings."}]},{"t":"p","runs":[{"text":"Anthropic’s format is different: "},{"text":"messages.create","code":true},{"text":" returns "},{"text":"content","code":true},{"text":" as a list of blocks, so code written against one SDK does not run against the other. If you may need to switch, keep the call in one function of your own and let only that function know which SDK it is using. Module 7 turns that into a class."}]},{"t":"h2","id":"reading-the-sdk","runs":[{"text":"Reading the SDK"}]},{"t":"p","runs":[{"text":"The single most useful habit with any library: find it and read it."}]},{"t":"code","lang":"python","label":"Python","text":"import openai\nprint(openai.__file__)\n# .../.venv/lib/python3.12/site-packages/openai/__init__.py"},{"t":"p","runs":[{"text":"Open that folder. "},{"text":"_client.py","code":true},{"text":" is the client, "},{"text":"_base_client.py","code":true},{"text":" has the retry loop with its backoff constants, and "},{"text":"resources/chat/completions.py","code":true},{"text":" is where "},{"text":"create","code":true},{"text":" lives, with every parameter documented in the signature. When the documentation site is vague about a default, the code is not."}]},{"t":"p","runs":[{"text":"help(client.chat.completions.create)","code":true},{"text":" in the shell prints the docstring without leaving the terminal. "},{"text":"inspect.signature(...)","code":true},{"text":" prints the parameters and defaults."}]},{"t":"h2","id":"which-to-use","runs":[{"text":"Which to use"}]},{"t":"p","runs":[{"text":"Use the SDK when one exists and the provider is your main dependency. Use "},{"text":"requests","code":true},{"text":" when the provider has no SDK, when the SDK is heavier than your whole program, when you need to see exactly what is sent, or when you are teaching yourself what an SDK does, which is what the first two lessons of this module were for."}]},{"t":"p","runs":[{"text":"Whichever you use, construct the client once. A new "},{"text":"OpenAI()","code":true},{"text":" inside a function called in a loop throws away the session each time and reintroduces every handshake you learned to avoid."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Install Ollama (free, runs on CPU), pull a small model with "},{"text":"ollama pull qwen2.5:0.5b","code":true},{"text":", and run the "},{"text":"base_url","code":true},{"text":" example with "},{"text":"model=\"qwen2.5:0.5b\"","code":true},{"text":". Then set "},{"text":"OPENAI_LOG=debug","code":true},{"text":" and run it again to see the request the SDK actually sent."}]}],"check":{"question":[{"text":"A developer’s script using the "},{"text":"openai","code":true},{"text":" package works against OpenAI’s API. They change only "},{"text":"base_url=\"http://localhost:11434/v1\"","code":true},{"text":" and "},{"text":"model=\"llama3.2\"","code":true},{"text":" to point it at Ollama running on their laptop, and it works too. What makes this possible?"}],"options":[{"text":[{"text":"The "},{"text":"openai","code":true},{"text":" package detects a localhost address and switches to a built-in local inference engine."}],"correct":false,"tempting":[{"text":"The package contains no model; it is an HTTP client, and it has no special handling for localhost."}]},{"text":[{"text":"Ollama serves an HTTP endpoint that accepts OpenAI’s request shape and returns its response shape, so the client code needs no change."}],"correct":true,"tempting":null},{"text":[{"text":"The SDK proxies the request to OpenAI and forwards the answer to the local server, which caches it so that later identical prompts are answered locally without a second round trip."}],"correct":false,"tempting":[{"text":"Nothing goes to OpenAI; the request travels only to the URL you configured, which is the whole point of "},{"text":"base_url","code":true},{"text":"."}]},{"text":[{"text":"Both services share a Python package, so the client imports Ollama’s code when it sees the model name."}],"correct":false,"tempting":[{"text":"There is no shared package; the compatibility lives in the HTTP request and response format, not in Python."}]}],"order":[0,3,2,1],"why":null},"prev":{"slug":"pagination-and-cursors","title":"Pagination: walking a result that arrives in pages","minutes":8},"next":{"slug":"consuming-a-stream","title":"Consuming a streamed reply: server-sent events, line by line","minutes":9}}}