docs: add readme and contributions guidelines

.github/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# 📗 Contribution Guidelines
+
+First off, thank you for your interest in contributing to the project! We welcome contributions from everyone. This document provides guidelines for contributing to the project.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+- Before submitting a bug report, make sure to check for [existing issues](https://github.com/vyfor/groq-kt/issues) to see if the problem has already been reported.
+- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/vyfor/groq-kt/issues/new). Be sure to include a clear title and description, along with as much relevant information as possible.
+
+### Suggesting Enhancements
+
+- Open a new issue with your suggestion, providing as much detail as possible.
+- Explain why this enhancement would be useful and whether it could introduce breaking changes to the codebase.
+
+### Pull Requests
+
+1. Fork the repo and create your branch from `master`.
+2. Add your changes and give it a proper testing.
+3. Make sure your code is formatted and lints.
+4. Issue that pull request!
+
+## Styleguides
+
+### Git Commit Messages
+
+We use the [Conventional Commits](https://www.conventionalcommits.org/) specification for our commit messages. This leads to more readable messages that are easy to follow when looking through the project history. Please adhere to this convention for your commit messages.
+
+The commit message should be structured as follows:
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+For breaking changes, add a `!` after the type/scope. Make sure to include the details in the commit body.
+
+Examples:
+
+`fix: user message serialization logic`
+
+`docs(readme): fix typo`
+
+`refactor!: remove deprecated function`
+
+## License
+By contributing to this project, you agree that your contributions will be licensed under the [MIT License](../LICENSE).

README.md

@@ -0,0 +1,115 @@
+# 📚 Groq Kotlin Library 
+
+![Maven Central Version](https://img.shields.io/maven-central/v/io.github.vyfor/groq-kt)
+
+**An idiomatic [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) library for the [Groq](https://groq.com/) API.**
+
+## 💎 Features
+- 🚀 Built on [Ktor](https://ktor.io/) for seamless networking
+- 🎨 Complete and documented API for chat completions, audio transcription, and translation, including tool support and function calling
+- ⚡ Real-time streaming responses via Kotlin Flows
+- 🧩 Rich, idiomatic DSL for clean and expressive syntax
+- 🔒 Ensures required validations are met before request submission
+- ⏳ Automatically handles rate limiting and retries on failed requests
+- 📱 Supports multiple platforms:
+  - Android
+  - iOS
+  - JavaScript
+  - JVM
+  - Linux
+  - macOS
+  - Windows
+  - WebAssembly
+  - tvOS, watchOS
+
+## 🔌 Requirements
+- Java 8 or higher (only for use within the JVM environment)
+
+## ⚙️ Installation
+
+Add these dependencies to your project:
+```kotlin
+dependencies {
+    implementation("io.github.vyfor:groq-kt:")
+    /* required */
+    implementation("io.ktor:ktor-client-$engine:$version")
+}
+```
+
+For the list of supported engines, see [Ktor Client Engines](https://ktor.io/docs/client-engines.html#platforms).
+
+## 🧩 Usage
+
+### Initialization
+```kotlin
+/* It is recommended to use an environment variable for the API key */
+val apiKey = System.getenv("GROQ_API_KEY")       // JVM
+val apiKey = process.env.GROQ_API_KEY            // JS
+val apiKey = getenv("GROQ_API_KEY")?.toKString() // Native
+
+val client = Groq(apiKey)
+```
+
+### Chat completion
+```kotlin
+val response = client.chat {
+    model = GroqModel.LLAMA_3_8B_8192
+
+    messages {
+        system("You are a helpful assistant.")
+        text("What is the capital of Germany?")
+    }
+}
+```
+
+### Streaming
+```kotlin
+val response = client.chatStreaming {
+    model = GroqModel.LLAMA_3_2_90B_VISION_PREVIEW
+
+    messages {
+        user(
+          "Describe what you see in the image.",
+          "https://example.com/image.png"
+        )
+    }
+}.data.collect { chunk ->
+    println(chunk)
+}
+```
+
+### Audio transcription
+```kotlin
+val response = client.transcribe {
+    model = GroqModel.DISTIL_WHISPER_LARGE_V3_EN
+
+    file("path/to/audio.mp3")
+    /* or */
+    url = "https://example.com/audio.mp3"
+}
+```
+
+### Audio translation
+> [!NOTE]
+> Does not seem to be supported by the API yet.
+```kotlin
+val response = client.translate {
+    model = GroqModel.DISTIL_WHISPER_LARGE_V3_EN
+
+    file("path/to/audio.mp3")
+    /* or */
+    url = "https://example.com/audio.mp3"
+}
+```
+
+## ⚖️ License
+`groq-kt` is licensed under the [MIT License](./LICENSE).
+
+The project is not affiliated with [Groq](https://groq.com/) in any way.
+
+## 📚 Documentation
+
+The REST API documentation can be found on [console.groq.com](https://console.groq.com/docs).
+
+## 🌱 Contributing
+This project is in beta. Contributions of any kind are welcome, just make sure you read the [Contribution Guidelines](./.github/CONTRIBUTING.md) first. You can also contact me directly on Discord (**[vyfor](https://discord.com/users/446729269872427018)**) if you have any questions.