docs: normalize README structure

README.md

@@ -1,70 +1,90 @@
 # Altertable Python SDK
 
-Official Python SDK for Altertable Product Analytics.
+You can use this SDK to send Product Analytics events to Altertable from Python applications.
 
-## Installation
-
-You can install the package via `pip`:
+## Install
 
 ```bash
 pip install altertable
 ```
 
-Or using `poetry`:
+## Quick start
 
-```bash
-poetry add altertable
+```python
+from altertable import Altertable
+
+client = Altertable("your_api_key")
+
+client.track(
+    event="button_clicked",
+    distinct_id="user_123",
+    options={"properties": {"button_id": "signup_btn", "page": "home"}},
+)
 ```
 
-## Usage
+## API reference
 
 ### Initialization
 
-```python
-from altertable import Altertable
+`Altertable(api_key: str)`
+
+Creates a client instance authenticated with your project API key.
 
+```python
 client = Altertable("your_api_key")
 ```
 
-### Tracking Events
+### Tracking
+
+`track(event: str, distinct_id: str, options: dict | None = None)`
+
+Sends an event for a user.
 
 ```python
-client.track(
-    event="button_clicked",
-    distinct_id="user_123",
-    options={
-        "properties": {
-            "button_id": "signup_btn",
-            "page": "home"
-        }
-    }
-)
+client.track("purchase", "user_123", options={"properties": {"amount": 42}})
 ```
 
-### Identifying Users
+### Identity
+
+`identify(distinct_id: str, options: dict | None = None)`
+
+Associates traits with a user.
 
 ```python
-client.identify(
-    distinct_id="user_123",
-    options={
-        "traits": {
-            "email": "user@example.com",
-            "name": "John Doe"
-        },
-        "anonymous_id": "previous_anon_id"
-    }
-)
+client.identify("user_123", options={"traits": {"email": "user@example.com"}})
 ```
 
 ### Alias
 
+`alias(distinct_id: str, new_user_id: str)`
+
+Merges an anonymous identifier into a known user identifier.
+
 ```python
-client.alias(
-    distinct_id="previous_anonymous_id",
-    new_user_id="new_user_id"
-)
+client.alias("anon_123", "user_123")
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `base_url` | `str` | `"https://api.altertable.ai"` | API base URL used for requests. |
+| `environment` | `str` | `"production"` | Environment tag attached to events. |
+| `request_timeout` | `int` | `5` | HTTP timeout in seconds. |
+| `release` | `str \| None` | `None` | Application release version. |
+| `debug` | `bool` | `False` | Enables debug logging output. |
+| `on_error` | `callable \| None` | `None` | Callback invoked on SDK errors. |
+
+## Development
+
+Prerequisites: Python 3.9+ and `pip`.
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
 ```
 
 ## License
 
-The package is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+See [LICENSE](LICENSE).