Merge pull request #6 from aptabase/ralph/llms-txt-agent-discovery

Add llms.txt for AI agent discoverability

Author: ivnbogdan

README.md

@@ -155,4 +155,6 @@ uv run mypy .
 
 ## License
 
-[MIT License](LICENSE)
+[MIT License](LICENSE)
+
+For AI/LLM integration instructions, see [llms.txt](./llms.txt)

llms.txt

@@ -0,0 +1,109 @@
+# Aptabase Python SDK
+
+> Privacy-first, open-source analytics for Python applications. Fully async, built with httpx and asyncio. Requires Python 3.11+. GDPR-compliant. No personal data collection.
+
+Package: `aptabase` on PyPI
+Repository: https://github.com/aptabase/aptabase-python
+
+## Installation
+
+```bash
+pip install aptabase
+# or
+uv add aptabase
+```
+
+## Quick Start (Context Manager)
+
+```python
+import asyncio
+from aptabase import Aptabase
+
+async def main():
+    async with Aptabase("A-EU-1234567890") as client:
+        await client.track("app_started")
+        await client.track("user_action", {"button": "login", "screen": "home"})
+
+asyncio.run(main())
+```
+
+## Quick Start (Manual Lifecycle)
+
+```python
+client = Aptabase("A-EU-1234567890")
+await client.start()
+try:
+    await client.track("app_started")
+finally:
+    await client.stop()  # Flushes remaining events
+```
+
+## Track Events
+
+```python
+# Simple event
+await client.track("page_view")
+
+# Event with properties (str, int, float values)
+await client.track("purchase", {
+    "product_id": "abc123",
+    "price": 29.99,
+    "currency": "USD"
+})
+```
+
+## Configuration
+
+```python
+client = Aptabase(
+    app_key="A-EU-1234567890",    # Required. Format: A-{EU|US|SH}-{ID}
+    app_version="1.2.3",          # App version string (default: "1.0.0")
+    is_debug=False,               # Enable debug mode (default: False)
+    max_batch_size=25,            # Max events per batch, max 25 (default: 25)
+    flush_interval=10.0,          # Auto-flush interval in seconds (default: 10.0)
+    timeout=30.0,                 # HTTP request timeout in seconds (default: 30.0)
+    base_url="https://self.host", # Required for self-hosted (A-SH-* keys)
+)
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| app_key | str | (required) | App key from Aptabase dashboard |
+| app_version | str | "1.0.0" | Your application version |
+| is_debug | bool | False | Debug mode flag |
+| max_batch_size | int | 25 | Max events per flush batch (hard max: 25) |
+| flush_interval | float | 10.0 | Seconds between auto-flushes |
+| timeout | float | 30.0 | HTTP request timeout in seconds |
+| base_url | str | None | Custom API URL (required for A-SH-* keys) |
+
+## Error Handling
+
+```python
+from aptabase import Aptabase, AptabaseError, NetworkError, ConfigurationError
+
+try:
+    async with Aptabase("A-EU-1234567890") as client:
+        await client.track("event")
+except NetworkError as e:
+    print(f"Network error: {e}, status: {e.status_code}")
+except ConfigurationError as e:
+    print(f"Config error: {e}")
+except AptabaseError as e:
+    print(f"Aptabase error: {e}")
+```
+
+## Platform Notes
+
+- Fully async — all methods are `async`/`await`
+- Requires Python 3.11+
+- Uses `httpx` for HTTP requests
+- Events are auto-batched and flushed every `flush_interval` seconds
+- Sessions auto-rotate after 1 hour of inactivity
+- Use context manager (`async with`) for automatic start/stop lifecycle
+- `flush()` can be called manually to force-send queued events
+- `stop()` flushes remaining events and closes the HTTP client
+- App key region determines API endpoint: `A-EU-*` → EU servers, `A-US-*` → US servers, `A-SH-*` → self-hosted (requires `base_url`)
+
+## Cross-Discovery
+
+For all Aptabase SDKs and documentation, see: https://aptabase.com/llms.txt