improve README

Author: Matthias Zimmermann

README.md

@@ -4,36 +4,23 @@ Arkiv is a permissioned storage system for decentralized apps, supporting flexib
 
 The Arkiv SDK is the official Python library for interacting with Arkiv networks. It offers a type-safe, developer-friendly API for managing entities, querying data, subscribing to events, and offchain verification—ideal for both rapid prototyping and production use.
 
-## SDK Architecture
+## Architecture
 
-### Principles
+Principles:
+- The SDK is based on a modern and stable client library.
+- The SDK should feel like "Library + Entities"
 
-SDK should be directly derived from one of the most well known and more recent client libraries.
-
-Highlevel goals:
-1. Go with the flow of the language and the library.
-2. Whatever works for the library should also work for the SDK
-3. Feels like "Library + Entities".
-
-### Underlying Library
-
-As underlying library we use [Web3.py](https://github.com/ethereum/web3.py) (no good alternatives).
-
-### Naming
-
-Github "Home": `arkiv-network`
-| Language | Element    | Name           | Comment                 |
-|----------|------------|----------------|-------------------------|
-| Python   | Repository | `arkiv-sdk-python` | Golem Base repo: `python-sdk` move and rename to `arkiv-python-beta` |
-| Python   | PIP        | `pip install arkiv-sdk`   | or `pip install arkiv` as `arkiv` is not available for Rust |
+As underlying library we use [Web3.py](https://github.com/ethereum/web3.py) (no good alternatives for Python).
 
 
 ### Arkiv Client
 
-Goal: Make Arkiv feel like "web3.py + entities", maintaining the familiar developer experience that Python web3 developers.
+The Arkiv SDK should feel like "web3.py + entities", maintaining the familiar developer experience that Python web3 developers.
 
-A `client.entities.*` approach for consistency with web3.py's module pattern. It clearly communicates that arkiv is a module extension just like eth, net, etc.
+A `client.arkiv.*` approach is in line with web3.py's module pattern.
+It clearly communicates that arkiv is a module extension just like eth, net, etc.
 
+## Hello World
 Here's a "Hello World!" example showing how to use the Python Arkiv SDK:
 
 ```python
@@ -49,8 +36,9 @@ provider = HTTPProvider('https://kaolin.hoodi.arkiv.network/rpc')
 account = NamedAccount.from_wallet('Alice', wallet, 's3cret')
 client = Arkiv(provider, account = account)
 
-# Check connection
+# Check connection and balance
 print(f"Connected: {client.is_connected()}")
+print(f"Account balance: {client.eth.get_balance(account.address)}")
 
 # Create entity with data and annotations
 entity_key, tx_hash = client.arkiv.create_entity(
@@ -66,16 +54,26 @@ print(f"Entity: {entity}")
 
 # TODO
 # Clean up - delete entities
-print("\n=== Cleanup ===")
 client.arkiv.delete_entity(entity_key)
 print("Entities deleted")
 
 # Verify deletion
-exists = client.arkiv.exists(entity_key1)
+exists = client.arkiv.exists(entity_key)
 print(f"Entity 1 exists? {exists}")
 ```
 
-Arkiv extensions
+### Web3 Standard Support
+```python
+from web3 import HTTPProvider
+provider = HTTPProvider('https://kaolin.hoodi.arkiv.network/rpc')
+
+# Arkiv 'is a' Web3 client
+client = Arkiv(provider)
+balance = client.eth.get_balance(client.eth.default_account)
+tx = client.eth.get_transaction(tx_hash)
+```
+
+### Arkiv Module Extension
 ```python
 from arkiv import Arkiv
 from arkiv.account import NamedAccount
@@ -90,90 +88,76 @@ entity_key, tx_hash = client.arkiv.create_entity(
 )
 
 entity = client.arkiv.get_entity(entity_key)
-````
+exists = client.arkiv.exists(entity_key)
+```
 
-Web3 standard
-```python
-from web3 import HTTPProvider
-provider = HTTPProvider('https://kaolin.hoodi.arkiv.network/rpc')
+## Development Guide
 
-# Arkiv 'is a' Web3 client
-client = Arkiv(provider)
-balance = client.eth.get_balance(client.eth.default_account)
-client.eth.get_transaction(tx_hash)
-````
+### Branches, Versions, Changes
 
-# Development Guide
+#### Branches
 
-## Code Quality and Type Safety
+The current stable branch on Git is `main`.
+Currently `main` hosts the initial SDK implementation.
 
-This project uses comprehensive linting and type checking to maintain high code quality:
+The branch `v1-dev` hosts the future V1.0 SDK release.
 
-### Tools Used
+#### Versions
 
-- **MyPy**: Static type checker with strict configuration
-- **Ruff**: Fast linter and formatter (replaces black, isort, flake8, etc.)
-- **Pre-commit**: Automated quality checks on git commits
+For version management the [uv](https://github.com/astral-sh/uv) package and project manger is used.
+Use the command below to display the current version
+```bash
+uv version
+```
+
+SDK versions are tracked in the following files:
+- `pyproject.toml`
+- `uv.lock`
+
+### Code Quality
+
+This project uses comprehensive unit testing, linting and type checking to maintain high code quality:
 
-### Quick Commands
+#### Quick Commands
 
+Before any commit run quality checks:
 ```bash
-# Run all quality checks
 ./scripts/check-all.sh
+```
+
+#### Tools Used
+
+- **MyPy**: Static type checker with strict configuration
+- **Ruff**: Fast linter and formatter (replaces black, isort, flake8, etc.)
+- **Pre-commit**: Automated quality checks on git commits
 
-# Individual tools
+#### Individual commands
+```bash
 uv run ruff check . --fix    # Lint and auto-fix
 uv run ruff format .         # Format code
 uv run mypy src/ tests/      # Type check
 uv run pytest tests/ -v     # Run tests
 uv run pytest --cov=src   # Run code coverage
+uv run pre-commit run --all-files # Manual pre commit checks
 ```
 
-### Pre-commit Hooks
+#### Pre-commit Hooks
 
 Pre-commit hooks run automatically on `git commit` and will:
 - Fix linting issues with ruff
 - Format code consistently
 - Run type checking with mypy
 - Check file formatting (trailing whitespace, etc.)
 
-To run pre-commit manually:
-```bash
-uv run pre-commit run --all-files
-```
-
-### Type Hints Best Practices
-
-1. **Always use type hints** for function parameters and return values
-2. **Use specific types** instead of `Any` when possible
-3. **Import types** from `typing` or `collections.abc` as needed
-4. **Use Union types** for multiple acceptable types: `str | int`
-5. **Generic containers**: `list[str]`, `dict[str, int]`, etc.
-
-### Example Type-Safe Code
-
-```python
-from collections.abc import Generator
-from typing import Any
-
-def process_data(items: list[dict[str, Any]]) -> Generator[str, None, None]:
-    """Process data items and yield formatted strings."""
-    for item in items:
-        if isinstance(item.get("name"), str):
-            yield f"Processing: {item['name']}"
-```
-
-### MyPy Configuration
+#### MyPy Settings
 
-The project uses strict mypy settings:
 - `strict = true` - Enable all strict checks
 - `no_implicit_reexport = true` - Require explicit re-exports
 - `warn_return_any = true` - Warn about returning Any values
 - Missing imports are ignored for third-party libraries without type stubs
 
-### Ruff Configuration
+#### Ruff Configuration
 
-Ruff is configured to:
 - Use 88 character line length (Black-compatible)
 - Target Python 3.12+ features
 - Enable comprehensive rule sets (pycodestyle, pyflakes, isort, etc.)