add documents

docs/examples/basic_usage.md

@@ -0,0 +1,204 @@
+# Basic Usage Example
+
+A complete example demonstrating basic usage of the FastGPT Python SDK.
+
+## Setup
+
+First, install the SDK and create a `.env` file:
+
+```bash
+pip install fastgpt-client python-dotenv
+```
+
+```bash
+# .env
+API_KEY=fastgpt-xxxxx
+BASE_URL=http://localhost:3000
+```
+
+## Complete Example
+
+```python
+"""Basic usage example for FastGPT Python SDK."""
+
+from fastgpt_client import ChatClient
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+# Configure your API key and base URL
+API_KEY = os.getenv("API_KEY")
+BASE_URL = os.getenv("BASE_URL")
+
+
+def simple_chat():
+    """Simple chat completion example."""
+    with ChatClient(api_key=API_KEY, base_url=BASE_URL) as client:
+        response = client.create_chat_completion(
+            messages=[{"role": "user", "content": "Hello! What's AI?"}],
+            stream=False
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        print("Response:", result['choices'][0]['message']['content'])
+
+
+def chat_with_history():
+    """Chat with message history example."""
+    with ChatClient(api_key=API_KEY, base_url=BASE_URL) as client:
+        response = client.create_chat_completion(
+            messages=[
+                {"role": "system", "content": "You are a helpful assistant."},
+                {"role": "user", "content": "Hello!"},
+                {"role": "assistant", "content": "Hi there! How can I help you?"},
+                {"role": "user", "content": "What's the capital of France?"}
+            ],
+            stream=False
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        print("Response:", result['choices'][0]['message']['content'])
+
+
+def multi_turn_conversation():
+    """Multi-turn conversation example."""
+    with ChatClient(api_key=API_KEY, base_url=BASE_URL) as client:
+        conversation = [
+            {"role": "user", "content": "What's Python?"}
+        ]
+
+        # First turn
+        response = client.create_chat_completion(
+            messages=conversation,
+            stream=False
+        )
+        response.raise_for_status()
+        result = response.json()
+        assistant_message = result['choices'][0]['message']['content']
+        print(f"AI: {assistant_message}")
+
+        # Add assistant response to conversation
+        conversation.append({"role": "assistant", "content": assistant_message})
+
+        # Second turn
+        conversation.append({"role": "user", "content": "Give me an example"})
+        response = client.create_chat_completion(
+            messages=conversation,
+            stream=False
+        )
+        response.raise_for_status()
+        result = response.json()
+        assistant_message = result['choices'][0]['message']['content']
+        print(f"AI: {assistant_message}")
+
+
+if __name__ == "__main__":
+    print("=== Simple Chat ===")
+    try:
+        simple_chat()
+    except Exception as e:
+        print(f"Error: {e}")
+
+    print("\n=== Chat with History ===")
+    try:
+        chat_with_history()
+    except Exception as e:
+        print(f"Error: {e}")
+
+    print("\n=== Multi-turn Conversation ===")
+    try:
+        multi_turn_conversation()
+    except Exception as e:
+        print(f"Error: {e}")
+```
+
+## Running the Example
+
+```bash
+python basic_usage.py
+```
+
+## Expected Output
+
+```
+=== Simple Chat ===
+Response: AI (Artificial Intelligence) is a branch of computer science...
+
+=== Chat with History ===
+Response: The capital of France is Paris.
+
+=== Multi-turn Conversation ===
+AI: Python is a high-level programming language...
+AI: Here's a simple example: print("Hello, World!")
+```
+
+## Key Concepts
+
+### Messages Array
+
+The `messages` parameter is an array of message objects:
+
+```python
+messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Hello!"},
+    {"role": "assistant", "content": "Hi there!"},
+    {"role": "user", "content": "How are you?"}
+]
+```
+
+### Response Structure
+
+The response follows OpenAI's format:
+
+```python
+{
+    "id": "chatcmpl-xxx",
+    "object": "chat.completion",
+    "created": 1234567890,
+    "model": "gpt-3.5-turbo",
+    "choices": [
+        {
+            "index": 0,
+            "message": {
+                "role": "assistant",
+                "content": "Response text here..."
+            },
+            "finish_reason": "stop"
+        }
+    ],
+    "usage": {
+        "prompt_tokens": 20,
+        "completion_tokens": 15,
+        "total_tokens": 35
+    }
+}
+```
+
+### Error Handling
+
+Always handle potential errors:
+
+```python
+from fastgpt_client import ChatClient
+from fastgpt_client.exceptions import APIError, AuthenticationError
+
+try:
+    with ChatClient(api_key=API_KEY) as client:
+        response = client.create_chat_completion(...)
+        response.raise_for_status()
+        result = response.json()
+except AuthenticationError:
+    print("Invalid API key")
+except APIError as e:
+    print(f"API error: {e}")
+```
+
+## See Also
+
+- [Streaming Example](streaming.md) - Learn how to use streaming responses
+- [Async Usage](async_usage.md) - Asynchronous examples
+- [Chat Context](chat_context.md) - Managing conversation context