swadhin / opengrammar public

docs: Perfected the README with API references, mobile instructions and collapsibles

Swadhin Biswas committed 7 months ago
5410575
1 parent bc27d51
commit 5410575
1 file changed
+68 -21
Showing 1 changed file+68-21
README.md
▼README.md
+68-21
@@ -11,21 +11,21 @@
11
11
[![Docker Pulls](https://img.shields.io/docker/pulls/swadhinbiswas/opengrammar-backend)](https://hub.docker.com/r/swadhinbiswas/opengrammar-backend)
12
12
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
13
13
14
- 🌐 **[Official Website](https://opengrammer.eu.cc)** | 📖 **[Documentation](https://opengrammer.eu.cc/docs)**
14
+ 🌐 **[Official Website](https://opengrammer.eu.cc)** | 📖 **[Documentation Site](https://opengrammer.eu.cc/docs)**
15
15
</div>
16
16
17
17
---
18
18
19
19
Writing clearly matters. But achieving perfect grammar shouldn't mean sacrificing your privacy or paying a premium monthly subscription to a tech giant.
20
20
21
-**OpenGrammar** is a powerful, robust intelligent writing assistant built from the ground up to match the premium writing tools you already know, but with one massive difference: **You own your data, and it runs completely for free.**
21
+**OpenGrammar** is a powerful intelligent writing assistant built to match the premium writing tools you already know, but with one massive difference: **You own your data, and it runs completely for free.**
22
22
23
23
## 🌟 Why OpenGrammar?
24
24
25
25
1. **The Zero-Cost Foundation:** Out of the box, our core engine runs 100% locally in your browser. With a massive 156,000-word offline dictionary, it instantly catches misspellings, passive voice, and weak phrasing without ever pinging a server.
26
-2. **Bring Your Own Brain (BYOK):** Want deep, context-aware AI corrections? Just plug in your own API key (OpenAI, Groq, Together, OpenRouter, or even local models via Ollama). You pay fractions of a cent exclusively for what you use.
27
-3. **Paranoid-Level Privacy:** We don't have a database. We don't want your user data. Your API key never leaves your browser storage. Text processed through the AI is immediately deleted via stateless edge functions.
28
-4. **Deploy It Yourself:** You own the entire pipeline. Host our lightweight backend instantly via Docker, npm, Cloudflare, Vercel, or Netlify.
26
+2. **Bring Your Own Brain (BYOK):** Want deep, context-aware AI corrections? Just plug in your own API key (OpenAI, Groq, Together, OpenRouter, or local models via Ollama). You pay fractions of a cent exclusively for what you use.
27
+3. **Paranoid-Level Privacy:** We don't have a database. We don't want your data. Your API key never leaves your browser storage. Text processed through the AI is immediately deleted via stateless edge functions.
28
+4. **Deploy It Yourself:** You own the entire pipeline. Host our lightweight backend instantly via Docker, NPM, Cloudflare, Vercel, or Netlify.
29
29
30
30
---
31
31
@@ -39,62 +39,109 @@ Don't want to host the backend yourself? OpenGrammar comes with incredibly fast,
39
39
40
40
---
41
41
42
-## 🛠️ Installation & Self-Hosting
42
+## 🛠️ Usage & Installation Environments
43
43
44
44
Our backend is natively multi-platform. Choose the environment that best fits your workflow.
45
45
46
-### 📦 Option 1: NPM / Mobile / Node Environments
47
-Run the OpenGrammar server on any machine with Node.js. You can effortlessly run this on an old laptop, a VPS, or even an Android phone using Termux!
46
+<details>
47
+<summary><b>📦 1. NPM / Mobile / Node Environments (Recommended for easy local use)</b></summary>
48
+
49
+Run the OpenGrammar server on any machine with Node.js. You can effortlessly run this on an old laptop, a Raspberry Pi, or even an Android phone using **Termux**!
48
50
49
51
```bash
50
52
# Run instantly without installing
51
53
npx opengrammar-server
52
54
53
55
# Or install globally for persistent usage
54
-npm install -g opengrammar-server
56
+npm i -g opengrammar-server
57
+
58
+# Start the server on port 8787
55
59
opengrammar-server --port 8787
56
60
```
57
61
58
-### 🐳 Option 2: Docker
62
+**📱 Android (Termux) Setup:**
63
+1. Install Termux.
64
+2. Run `pkg update && pkg install nodejs`.
65
+3. Run `npx opengrammar-server`. Your phone is now a local grammar API!
66
+</details>
67
+
68
+<details>
69
+<summary><b>🐳 2. Docker Setup</b></summary>
70
+
59
71
We maintain a highly optimized, multi-architecture Docker image. This is the recommended route for standard server environments or local homelabs.
60
72
61
73
```bash
62
-# Pull the production image
74
+# Pull the production image straight from Docker Hub
63
75
docker pull swadhinbiswas/opengrammar-backend:latest
64
76
65
-# Run the container (exposes port 8787)
77
+# Run the container locally (exposes port 8787)
66
78
docker run -d -p 8787:8787 --name opengrammar swadhinbiswas/opengrammar-backend:latest
67
79
```
80
+</details>
68
81
69
-### 🧩 Option 3: Browser Extension (For Users)
82
+<details>
83
+<summary><b>🧩 3. Browser Extension (For End Users)</b></summary>
70
84
71
85
1. Download the latest release from the `opengrammar/extension/dist` build.
72
86
2. Open Chrome/Brave/Edge and navigate to `chrome://extensions/`.
73
87
3. Enable **Developer Mode**.
74
88
4. Click **Load unpacked** and select the extension folder.
75
-5. Click the OpenGrammar feather icon in your toolbar, input your custom AI API keys, and link it to one of the **Live Production Endpoints** listed above!
89
+5. Click the OpenGrammar feather icon in your toolbar, input your custom AI API keys, and optionally link the Server URL to one of our **Live Production Endpoints** above!
90
+</details>
91
+
92
+---
93
+
94
+## 🔌 API Reference & Environment Variables
95
+
96
+If you are hosting OpenGrammar yourself via Docker or NPM, you have full access to its modular REST API endpoints.
97
+
98
+### Environment Variables (.env)
99
+Create a `.env` file in your runtime directory to configure the AI routing logic.
100
+
101
+| Variable | Description |
102
+|----------|-------------|
103
+| `PORT` | Server port (default: `8787`) |
104
+| `GROQ_API_KEY` | Groq API key for ultra-fast AI grammar rewriting |
105
+| `OPENAI_API_KEY` | OpenAI API key for premium AI models |
106
+
107
+### Endpoints
108
+
109
+| Method | Endpoint | Description |
110
+|--------|----------|-------------|
111
+| `GET` | `/` | Status dashboard & Engine Version |
112
+| `GET` | `/health` | Server health check |
113
+| `POST` | `/analyze` | Advanced grammar analysis |
114
+| `POST` | `/autocomplete`| AI Context-aware text completion |
115
+| `GET` | `/providers` | Returns configured AI providers |
116
+
117
+**Example Request:**
118
+```bash
119
+curl -X POST http://localhost:8787/analyze \
120
+ -H "Content-Type: application/json" \
121
+ -d '{"text": "Me and him went to store yesterday."}'
122
+```
76
123
77
124
---
78
125
79
-## ✨ Core Features
126
+## ✨ Application Features
80
127
81
128
- **The Dual-Engine Architecture:** A blazing fast local (offline) RegEx + Dictionary matching engine, paired securely with a configurable LLM router framework for tone rewriting and smart context adjustments.
82
129
- **Deduplication Logic:** The AI is fully synchronized with the local spellchecker. It never wastes expensive AI tokens re-checking typos already caught locally.
83
130
- **Smart Context Awareness:** Automatically detects if you are writing a casual tweet, a technical document, or a formal business email, scaling its strictness appropriately.
84
131
- **Dynamic Writing Score:** Evaluates your text dynamically (0-100) based on Correctness, Readability, Engagement, and Sentence Delivery.
85
-- **Flawless Integrations:** Securely injects into rich-text editors including Gmail, Google Docs, Notion, and Reddit.
132
+- **Flawless Integrations:** Securely injects into rich-text editors including Gmail, GoogleDocs, Notion, and Reddit.
86
133
87
134
---
88
135
89
-## 🤝 Join the Rebellion
136
+## 🤝 Contributing
90
137
91
138
**We need your help to unseat the monopolies and make OpenGrammar the definitive open-source writing assistant.**
92
139
93
-Whether you are a TypeScript developer wanting to optimize edge latency, or a language nerd looking to build out our offline Regex `GRAMMAR_RULES.md`—we want you!
140
+Whether you are a TypeScript developer wanting to optimize Vercel Edge latency, or a language nerd looking to build out our offline Regex `GRAMMAR_RULES.md`—we want you!
94
141
95
-- Read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide.
96
-- Check our `ROADMAP.md` to see what we are currently building.
97
-- Open an issue for bugs or start a thread in our Discussions tab.
142
+- Read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide to get started locally.
143
+- Check our `ROADMAP.md` to see what features we are currently building.
144
+- Found a bug? Open an Issue. Have an idea? Start a thread in our Discussions tab.
98
145
99
146
## 📄 License
100
147
101
148