Comprehensive README enhancement with accurate API documentation and development guidelines

[Copilot]

• Explored repository structure and understood the project
• Analyzed current README.md content
• Reviewed project configuration (pyproject.toml, setup.py, Makefile)
• Examined package structure and available components
• Identified key information missing from README
• Created comprehensive README improvements including:
  • Added badges for build status, Python version, license, and code style
  • Enhanced project description with clear value proposition
  • Added detailed feature list with technical specifications
  • Provided accurate installation instructions (PyPI, source, dev)
  • Created realistic usage examples based on actual test code
  • Added proper API documentation with correct method signatures
  • Included performance characteristics and benefits
  • Added development setup instructions
  • Created project structure overview
  • Added contribution guidelines, platform support, requirements
  • Included license information and related project links
• Fixed Python version requirements to match CI configuration (3.11+)
• Created CONTRIBUTING.md file with development workflows
• Validated examples against actual codebase implementation
• Updated installation instructions to reflect alpha development status
• Added development status section to set proper expectations
• Enhanced build instructions with virtual environment setup
• Updated both README and CONTRIBUTING.md with virtual environment recommendations

Original prompt

can you review the readme for this repo please

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

📦 Draken build version: 0.0.1-alpha.48

[joocer]

@copilot

did I accidentally stop you when I took the PR out of draft? you can resume please

[github-actions]

📦 Draken build version: 0.0.1-alpha.48