fix: add proper imports and modernize README

- Add blank lines after imports for PEP 8 compliance
- Modernize README with badges, quick start, and streaming examples

Author: Patel230

README.md

@@ -1,6 +1,26 @@
-# hawk-sdk
-
-Python SDK for the [Hawk](https://github.com/hawk-eco/hawk) daemon API.
+<p align="center">
+  <h1 align="center">Hawk SDK for Python</h1>
+  <p align="center">
+    <strong>Official Python client for the Hawk daemon API</strong>
+  </p>
+  <p align="center">
+    <a href="https://python.org/"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
+    <a href="https://github.com/GrayCodeAI/hawk-sdk-python/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/GrayCodeAI/hawk-sdk-python/ci.yml?style=flat-square&label=tests" alt="CI"></a>
+  </p>
+</p>
+
+---
+
+The Hawk SDK for Python provides an idiomatic client for interacting with the [Hawk](https://github.com/GrayCodeAI/hawk) daemon API. It supports both synchronous and async operations, including streaming.
+
+## Features
+
+- **Sync and async** - Use `HawkClient` or `AsyncHawkClient`
+- **Streaming support** - Real-time response streaming
+- **Context managers** - Automatic resource cleanup
+- **Type hints** - Full type annotations for IDE support
+- **Error handling** - Detailed exception types
 
 ## Installation
 
@@ -14,191 +34,38 @@ pip install hawk-sdk
 from hawk import HawkClient
 
 with HawkClient() as client:
-    # Check health
+    # Health check
     health = client.health()
-    print(f"Status: {health.status}, Version: {health.version}")
+    print(f"Version: {health.version}")
 
     # Chat
-    response = client.chat("Explain async/await in Python")
+    response = client.chat("Explain decorators in Python")
     print(response.response)
 ```
 
 ## Async Usage
 
 ```python
-import asyncio
 from hawk import AsyncHawkClient
 
-async def main():
-    async with AsyncHawkClient() as client:
-        response = await client.chat("Hello!")
-        print(response.response)
-
-asyncio.run(main())
+async with AsyncHawkClient() as client:
+    response = await client.chat("Hello!")
+    print(response.response)
 ```
 
 ## Streaming
 
 ```python
-from hawk import HawkClient
-
 with HawkClient() as client:
     with client.chat_stream("Write a haiku") as stream:
         for event in stream.events():
             print(event.data, end="", flush=True)
-        print()
-```
-
-Or collect the full text:
-
-```python
-with HawkClient() as client:
-    with client.chat_stream("Write a haiku") as stream:
-        text = stream.collect_text()
-        print(text)
-```
-
-## Tools
-
-```python
-from hawk import HawkClient, Tool, tool, chat_with_tools
-
-@tool(
-    name="get_weather",
-    description="Get current weather for a location",
-    parameters={
-        "type": "object",
-        "properties": {"location": {"type": "string"}},
-        "required": ["location"],
-    },
-)
-def get_weather(location: str) -> str:
-    return f"Sunny, 72F in {location}"
-
-with HawkClient() as client:
-    response = chat_with_tools(
-        client,
-        "What's the weather in NYC?",
-        tools=[get_weather],
-    )
-    print(response.response)
-```
-
-## Workflow
-
-```python
-from hawk import Workflow
-from hawk.retry import RetryConfig
-
-def fetch(url: str) -> str:
-    import httpx
-    return httpx.get(url).text
-
-def summarize(text: str) -> str:
-    # Process the text
-    return text[:100]
-
-wf = (
-    Workflow("fetch-and-summarize")
-    .step("fetch", fetch, timeout=10.0)
-    .step("summarize", summarize, retry=RetryConfig(max_retries=2))
-    .build()
-)
-
-result = wf.run("https://example.com")
-```
-
-## Agent
-
-```python
-from hawk import HawkClient, Agent, AgentConfig, Tool
-
-weather_tool = Tool(
-    name="get_weather",
-    description="Get weather",
-    parameters={"type": "object", "properties": {"location": {"type": "string"}}},
-    fn=lambda location: f"72F in {location}",
-)
-
-with HawkClient() as client:
-    agent = Agent(client, AgentConfig(
-        name="weather-bot",
-        model="claude-sonnet-4-20250514",
-        tools=[weather_tool],
-    ))
-
-    response = agent.chat("What's the weather in San Francisco?")
-    print(response.response)
-
-    # Conversation history is maintained
-    response = agent.chat("What about New York?")
-    print(response.response)
-```
-
-## Sessions
-
-```python
-from hawk import HawkClient
-
-with HawkClient() as client:
-    # List sessions
-    sessions = client.list_sessions(limit=10)
-    for s in sessions.data:
-        print(f"{s.id}: {s.turns} turns")
-
-    # Get session details
-    detail = client.get_session("session-id")
-    print(f"Model: {detail.model}, Messages: {detail.message_count}")
-
-    # Get messages
-    messages = client.list_messages("session-id")
-    for m in messages.data:
-        print(f"[{m.role}] {m.content}")
-
-    # Delete session
-    client.delete_session("session-id")
-```
-
-## Configuration
-
-```python
-from hawk import HawkClient, RetryConfig
-
-client = HawkClient(
-    base_url="http://localhost:4590",  # Daemon URL
-    api_key="sk-...",                  # Optional API key
-    timeout=60.0,                      # Request timeout in seconds
-    retry_config=RetryConfig(
-        max_retries=5,
-        initial_backoff=1.0,
-        max_backoff=60.0,
-    ),
-)
-```
-
-## Error Handling
-
-```python
-from hawk import HawkClient, NotFoundError, RateLimitError, HawkAPIError
-
-with HawkClient() as client:
-    try:
-        session = client.get_session("nonexistent")
-    except NotFoundError as e:
-        print(f"Not found: {e.message}")
-    except RateLimitError as e:
-        print(f"Rate limited, retry after {e.retry_after}s")
-    except HawkAPIError as e:
-        print(f"API error {e.status_code}: {e.message}")
 ```
 
-## Development
+## Examples
 
-```bash
-pip install -e ".[dev]"
-pytest
-```
+See the [examples/](examples/) directory for complete runnable examples.
 
 ## License
 
-MIT
+MIT - see [LICENSE](LICENSE) for details.

examples/basic/main.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 """Basic example of using the Hawk SDK."""
 
-from hawk import HawkClient
+from hawk import HawkClient  # noqa: E402
+
 
 def main():
     with HawkClient() as client:
@@ -20,5 +21,6 @@ def main():
                 print(event.data, end="", flush=True)
         print()
 
+
 if __name__ == "__main__":
     main()