Update docs

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to Apache ResilientDB Python SDK
+
+We love your input! We want to make contributing to Apache ResilientDB Python SDK as easy and transparent as possible, whether it's:
+
+- Reporting a bug
+- Discussing the current state of the code
+- Submitting a fix
+- Proposing new features
+- Becoming a maintainer
+
+## Development Process
+
+We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.
+
+1. Fork the repo and create your branch from `main`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code follows the project's coding standards.
+6. Issue that pull request!
+
+## Development Setup
+
+1. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/incubator-resilientdb-python-sdk.git
+   cd incubator-resilientdb-python-sdk
+   ```
+
+2. Set up development environment:
+   ```bash
+   sh INSTALL.sh
+   python3.10 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+   ```
+
+3. Create a branch:
+   ```bash
+   git checkout -b your-feature-name
+   ```
+
+## Coding Standards
+
+- Follow PEP 8 style guide for Python code
+- Use type hints for function parameters and return values
+- Write docstrings for all public methods and classes
+- Keep functions focused and concise
+- Add comments for complex logic
+- Include unit tests for new functionality
+
+## Pull Request Process
+
+1. Update the README.md with details of changes to the interface, if applicable.
+2. Update the documentation with details of any new functionality.
+3. The PR will be merged once you have the sign-off of at least one maintainer.
+
+
+## Issue Reporting Guidelines
+
+
+### Bug Reports
+
+When filing an issue, make sure to answer these questions:
+
+1. What version of Python are you using?
+2. What operating system are you using?
+3. What did you do?
+4. What did you expect to see?
+5. What did you see instead?
+
+### Feature Requests
+
+We welcome feature requests! When submitting a feature request, please:
+
+1. Explain the problem you're trying to solve
+2. Describe the solution you'd like to see
+3. Provide context about alternative solutions you've considered
+
+## Community
+
+- Subscribe to our [mailing lists](https://lists.apache.org/list.html?dev@resilientdb.apache.org)
+- Join our discussions on [GitHub Issues](https://github.com/apache/incubator-resilientdb-python-sdk/issues)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0.

README.md

@@ -1,52 +1,203 @@
-# ResilientDB SDK
+# Apache ResilientDB Python SDK (Incubating)
 
-## Check Python is up-to-date (3.9+)
-`$ python3 --version`
+<div align="center">
+
+[![Apache License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Python Versions](https://img.shields.io/badge/python-3.9%2B-blue)](https://github.com/apache/incubator-resilientdb-python-sdk)
+[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](./docs)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
 
-If your Python version number is too low you may encounter type hinting issues when attempting to run the code. You can use a Python virtual environment, as shown below.
+High-performance blockchain database SDK for Python applications
+
+[Quick Start](#quick-start) •
+[Documentation](#documentation) •
+[Examples](#examples) •
+[Contributing](#contributing) •
+[Support](#support)
 
-## First-time set up
+</div>
 
-`$ sh INSTALL.sh`
+> [!NOTE]  
+> Apache ResilientDB is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects.
 
-`$ python3.10 -m venv venv`
+## 🚀 Quick Start
 
-`$ source venv/bin/activate`
+### Installation
 
-`$ pip install -r requirements.txt`
+```bash
+# Clone the repository
+git clone https://github.com/apache/incubator-resilientdb-python-sdk.git
+cd incubator-resilientdb-python-sdk
 
-The correct Python configuration is needed for transaction validation.
+# Set up the environment
+sh INSTALL.sh
+python3.10 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
 
-## Running KV service
+### Basic Usage
 
-If your virtual environment is not already active:
+```python
+from resdb_driver import Resdb
+from resdb_driver.crypto import generate_keypair
+from typing import Dict, Any
 
-`$ source venv/bin/activate`
+# Initialize the client
+db = Resdb('http://127.0.0.1:18000')
+
+# Generate keypairs for the example
+alice, bob = generate_keypair(), generate_keypair()
+
+# Create a digital asset
+asset = {
+    "data": {
+        "token_for": "example",
+        "description": "Example token",
+    },
+}
 
-Run the script to start 4 local nodes
+# Prepare transaction
+prepared_tx = db.transactions.prepare(
+    operation='CREATE',
+    signers=alice.public_key,
+    recipients=[([bob.public_key], 10)],  # Transfer 10 tokens to Bob
+    asset=asset,
+)
 
-`$ sh service/tools/start_kv_service_sdk.sh`
+# Sign the transaction
+fulfilled_tx = db.transactions.fulfill(
+    prepared_tx, 
+    private_keys=alice.private_key
+)
 
-## Running Crow service (HTTP endpoints)
+# Send the transaction
+tx_id_str = db.transactions.send_commit(fulfilled_tx)
 
-`$ bazel build service/http_server/crow_service_main`
 
-`$ bazel-bin/service/http_server/crow_service_main service/tools/config/interface/client.config service/http_server/server_config.config`
+# Retrieve the transaction
+result = db.transactions.retrieve(fulfilled_tx["id"])
+print(f"Retrieved transaction: {result}")
+```
 
-For a list of endpoints visit [here](./service/http_server/README.md)
+## 🌟 Features
 
-## Testing
+- **Transaction Management**
+  - Create and send transactions with digital signatures
+  - Retrieve and query transaction details
+  - Asset-based transaction querying
 
-`$ bazel-bin/service/kv_service/kv_service_tools service/tools/config/interface/service.config set test 1234`
+- **Block Operations**
+  - Retrieve blocks by transaction
+  - Query block ranges
+  - Real-time block updates
 
-## Running the driver
+- **Asset & Metadata Management**
+  - Asset search and retrieval
+  - Metadata management
+  - Output tracking
 
-Examples of using the driver can be seen in [test_driver](/test_driver.py)
+- **DB Connection**
+  - Automatic failover
+  - Round-robin load balancing
+  - Connection pooling
+  - Exponential backoff
 
-Replace the db_root_url with the address of the ResilientDB HTTP endpoints e.g. `127.0.0.1:18000`
+## 📋 Requirements
 
+- Python 3.9 or higher
+- Bazel build system
+- Debian based linux distros e.g. Ubuntu
+- Virtual environment (recommended)
 
-## TODO
-- Setting up linting (using [black](https://github.com/psf/black)) through github hooks
-- convert the sdk into a package (for pip install)
-- Potentially have a docker setup which fetched the Resdb image and runs it locally
+## 🔧 Setup & Configuration
+
+### 1. Start the Key-Value Service
+
+```bash
+source venv/bin/activate
+sh service/tools/start_kv_service_sdk.sh
+```
+
+### 2. Start the HTTP Service
+
+```bash
+bazel build service/http_server/crow_service_main
+bazel-bin/service/http_server/crow_service_main \\
+    service/tools/config/interface/client.config \\
+    service/http_server/server_config.config
+```
+
+## 📚 Documentation
+
+- [Complete API Reference](./docs/api_reference.md)
+- [HTTP Endpoints Guide](./service/http_server/README.md)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+- [Example Use Cases](./test_driver_2.py)
+
+## 🏗️ Project Structure
+
+```
+resilientdb-python-sdk/
+├── docs/               # Documentation and guides
+├── resdb_driver/      # Core SDK implementation
+├── service/           # Service implementations
+│   ├── http_server/   # HTTP API service (Crow)
+│   └── kv_service/    # Key-Value service
+└── test/              # Test suite
+```
+
+## 🧪 Testing
+TODO: add tests
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+1. **Connection Refused**
+   ```
+   Solution: Ensure the HTTP service is running on port 18000
+   ```
+
+2. **Python Version Mismatch**
+   ```
+   Solution: Use Python 3.9 or higher, preferably in a virtual environment
+   ```
+
+3. **Bazel Build Failures**
+   ```
+   Solution: Check Bazel version and ensure all dependencies are installed
+   ```
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guidelines](./CONTRIBUTING.md) for:
+- How to submit patches
+- Development workflow
+- Coding standards
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 💬 Support
+
+- [GitHub Issues](https://github.com/apache/incubator-resilientdb-python-sdk/issues)
+- [Mailing Lists](https://lists.apache.org/list.html?dev@resilientdb.apache.org)
+
+## 🗺️ Roadmap
+
+### Current Goals
+- [ ] Setting up linting (using [black](https://github.com/psf/black))
+- [ ] Convert to pip-installable package
+- [ ] Docker setup for local ResilientDB
+
+### Connection Improvements
+- [ ] Connection encryption and authentication options
+- [ ] Load balancing strategies
+- [ ] Metrics and monitoring
+
+### API Enhancements
+- [ ] Add async/await support using aiohttp
+- [ ] Improve transaction ID handling