{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# eve-api Tutorial\n",
    "\n",
    "A quick walkthrough of the `eve-api` package: a minimal authenticated HTTP client for the EVE API.\n",
    "\n",
    "## Installation\n",
    "\n",
    "```bash\n",
    "cd eve-api\n",
    "pip install -e .\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Connect and log in"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from eve_api import EVEClient\n",
    "\n",
    "eve = EVEClient()          # defaults to https://api.eve-chat.chat\n",
    "await eve.__aenter__()     # open the HTTP connection\n",
    "\n",
    "await eve.login(\"your-email@example.com\", \"your-password\")\n",
    "print(\"Authenticated:\", eve.is_authenticated())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. GET requests\n",
    "\n",
    "All convenience methods (`get`, `post`, `patch`, `delete`) return parsed JSON as plain Python dicts/lists."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "me = await eve.get(\"/users/me\")\n",
    "print(f\"User: {me['email']}\")\n",
    "print(f\"Name: {me.get('first_name', '')} {me.get('last_name', '')}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "collections = await eve.get(\"/collections/public\")\n",
    "\n",
    "for col in collections[\"data\"]:\n",
    "    print(f\"  - {col['name']}\")\n",
    "\n",
    "print(f\"\\nTotal: {collections['meta']['total_count']}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. POST, PATCH, DELETE"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a conversation\n",
    "conv = await eve.post(\"/conversations\", json={\"name\": \"Tutorial Chat\"})\n",
    "conv_id = conv[\"id\"]\n",
    "print(f\"Created: {conv_id} — {conv['name']}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Rename it\n",
    "updated = await eve.patch(f\"/conversations/{conv_id}\", json={\"name\": \"Renamed Chat\"})\n",
    "print(f\"Renamed to: {updated['name']}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Delete it\n",
    "await eve.delete(f\"/conversations/{conv_id}\")\n",
    "print(\"Deleted.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Streaming a response\n",
    "\n",
    "The `stream()` method yields parsed SSE event dicts as they arrive from the server."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "conv = await eve.post(\"/conversations\", json={\"name\": \"Stream Demo\"})\n",
    "conv_id = conv[\"id\"]\n",
    "\n",
    "async for event in eve.stream(\n",
    "    f\"/conversations/{conv_id}/stream_messages\",\n",
    "    json={\n",
    "        \"query\": \"What is Synthetic Aperture Radar?\",\n",
    "        \"public_collections\": [\"eve-public\"],\n",
    "        \"k\": 3,\n",
    "    },\n",
    "):\n",
    "    if event[\"type\"] == \"token\":\n",
    "        print(event[\"content\"], end=\"\", flush=True)\n",
    "    elif event[\"type\"] == \"status\":\n",
    "        print(f\"[{event['content']}]\", flush=True)\n",
    "    elif event[\"type\"] == \"final\":\n",
    "        print()  # newline after streaming completes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Clean up\n",
    "await eve.delete(f\"/conversations/{conv_id}\")\n",
    "print(\"Conversation deleted.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Unauthenticated requests\n",
    "\n",
    "Use `request()` with `auth_required=False` for endpoints that do not need a token. This returns the raw `httpx.Response`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "resp = await eve.request(\"GET\", \"/health\", auth_required=False)\n",
    "print(f\"Status: {resp.status_code}\")\n",
    "print(resp.json())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Direct token access\n",
    "\n",
    "Useful if you need to pass the token to another library or service."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Token:\", eve.token[:20], \"...\")\n",
    "print(\"Headers:\", eve.auth_headers)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Error handling\n",
    "\n",
    "The client raises typed exceptions for common HTTP error codes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from eve_api import NotFoundError, ForbiddenError, APIError\n",
    "\n",
    "try:\n",
    "    await eve.get(\"/conversations/nonexistent-id\")\n",
    "except NotFoundError:\n",
    "    print(\"Not found (404)\")\n",
    "except ForbiddenError:\n",
    "    print(\"Forbidden (403)\")\n",
    "except APIError as e:\n",
    "    print(f\"API error {e.status_code}: {e.message}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Clean up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "await eve.close()\n",
    "print(\"Connection closed.\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "geostars",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}