Skip to content

Commit 98d730e

Browse files
dev-damidev-dami
committed
docs: add professional docs site with motion and spacing system
1 parent b38c826 commit 98d730e

16 files changed

Lines changed: 791 additions & 31 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- develop
8+
pull_request:
9+
branches:
10+
- main
11+
- develop
12+
13+
jobs:
14+
test-and-build:
15+
runs-on: ubuntu-latest
16+
timeout-minutes: 20
17+
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Bun
23+
uses: oven-sh/setup-bun@v2
24+
with:
25+
bun-version: latest
26+
27+
- name: Install dependencies
28+
run: bun install --frozen-lockfile
29+
30+
- name: Build
31+
run: bun run build
32+
33+
- name: Run test suite
34+
run: bun run test
35+
36+
- name: Coverage
37+
run: bun run test:coverage
38+
39+
- name: Upload coverage artifacts
40+
if: always()
41+
uses: actions/upload-artifact@v4
42+
with:
43+
name: coverage-report
44+
path: |
45+
coverage/lcov-report
46+
coverage/lcov.info
47+
if-no-files-found: warn

‎.github/workflows/release.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
workflow_dispatch:
8+
9+
jobs:
10+
publish:
11+
runs-on: ubuntu-latest
12+
timeout-minutes: 20
13+
14+
permissions:
15+
contents: read
16+
17+
steps:
18+
- name: Checkout
19+
uses: actions/checkout@v4
20+
21+
- name: Setup Bun
22+
uses: oven-sh/setup-bun@v2
23+
with:
24+
bun-version: latest
25+
26+
- name: Setup Node (npm publish auth)
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: "20"
30+
registry-url: "https://registry.npmjs.org"
31+
32+
- name: Install dependencies
33+
run: bun install --frozen-lockfile
34+
35+
- name: Build
36+
run: bun run build
37+
38+
- name: Test
39+
run: bun run test
40+
41+
- name: Publish to npm
42+
if: ${{ secrets.NPM_TOKEN != '' }}
43+
run: npm publish --access public
44+
env:
45+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
46+
47+
- name: Skip publish (missing token)
48+
if: ${{ secrets.NPM_TOKEN == '' }}
49+
run: echo "NPM_TOKEN is not configured. Release checks ran, publish skipped."

‎README.MD‎

Lines changed: 69 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,82 +2,120 @@
22

33
<div align="center">
44

5+
**TypeScript NLP pipeline for fast, structured text understanding**
6+
7+
[![CI](https://github.com/dev-dami/Qirrel/actions/workflows/ci.yml/badge.svg)](https://github.com/dev-dami/Qirrel/actions/workflows/ci.yml)
8+
[![CD](https://github.com/dev-dami/Qirrel/actions/workflows/release.yml/badge.svg)](https://github.com/dev-dami/Qirrel/actions/workflows/release.yml)
59
[![NPM Version](https://img.shields.io/npm/v/qirrel.svg)](https://www.npmjs.com/package/qirrel)
610
[![NPM Downloads](https://img.shields.io/npm/dm/qirrel.svg)](https://www.npmjs.com/package/qirrel)
711
[![License](https://img.shields.io/npm/l/qirrel.svg)](./LICENSE)
812
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
913

14+
[GitHub](https://github.com/dev-dami/Qirrel) · [NPM](https://www.npmjs.com/package/qirrel) · Author: [Damilare Osibanjo](https://github.com/dev-dami)
15+
1016
</div>
1117

12-
Qirrel is a TypeScript NLP library for tokenization, rule-based entity extraction, optional LLM enrichment, and pipeline orchestration.
18+
## Why Qirrel
19+
20+
Qirrel gives you a production-ready pipeline for extracting structure from raw text:
1321

14-
[GitHub](https://github.com/dev-dami/qirrel) | [NPM](https://www.npmjs.com/package/qirrel) | Author: [Damilare Osibanjo](https://github.com/dev-dami)
22+
- Tokenization with positional metadata.
23+
- Rule-based extraction for email, phone, URL, and number entities.
24+
- Optional LLM enrichment via adapter pattern.
25+
- Built-in caching and lifecycle events.
26+
- Batch processing with controllable concurrency.
1527

1628
## Install
1729

1830
```bash
1931
bun add qirrel
2032
```
2133

22-
## Quick Start
34+
## 30-Second Start
2335

2436
```ts
2537
import { processText } from 'qirrel';
2638

27-
const result = await processText('Contact John at john@example.com or call +1 415 555 2671');
39+
const result = await processText(
40+
'Contact Jane at jane@example.com or +44 20 7946 0958',
41+
);
42+
2843
console.log(result.data?.entities);
2944
```
3045

31-
## Batch Processing
46+
## Core Features
47+
48+
| Feature | API | Notes |
49+
| --- | --- | --- |
50+
| Single-text processing | `processText(text)` | Returns `QirrelContext` |
51+
| Batch processing | `processTexts(texts, configPath?, { concurrency })` | Keeps input order |
52+
| Custom pipeline | `new Pipeline(configPath?)` | Add processors and hooks |
53+
| Events | `pipeline.on(PipelineEvent.*, handler)` | Run/processor/error telemetry |
54+
| Caching | `pipeline.isCached/getCached/setCached` | LRU + TTL |
55+
| LLM adapter | `pipeline.getLLMAdapter()` | `gemini`, `openai`, `generic` |
56+
57+
## Batch Example
3258

3359
```ts
34-
import { processTexts, Pipeline } from 'qirrel';
60+
import { processTexts } from 'qirrel';
3561

36-
const results = await processTexts(['first input', 'second input'], undefined, { concurrency: 2 });
62+
const inputs = [
63+
'US: +1 415 555 2671',
64+
'URL: https://example.com',
65+
'Email: team@example.com',
66+
];
3767

38-
const pipeline = new Pipeline();
39-
const ordered = await pipeline.processBatch(['a', 'b', 'c'], { concurrency: 3 });
68+
const outputs = await processTexts(inputs, undefined, { concurrency: 2 });
69+
console.log(outputs.map((o) => o.data?.entities));
4070
```
4171

42-
## LLM Integration
72+
## LLM Example
4373

4474
```ts
4575
import { Pipeline } from 'qirrel';
4676

4777
const pipeline = new Pipeline('./config-with-llm.yaml');
4878
await pipeline.init();
4979

50-
const llmAdapter = pipeline.getLLMAdapter();
51-
if (llmAdapter) {
52-
const response = await llmAdapter.generate('Summarize this text: Hello world');
80+
const adapter = pipeline.getLLMAdapter();
81+
if (adapter) {
82+
const response = await adapter.generate('Summarize: Qirrel is an NLP pipeline.');
5383
console.log(response.content);
5484
}
5585
```
5686

57-
## Caching
87+
## Minimal LLM Config
5888

59-
```ts
60-
import { Pipeline } from 'qirrel';
89+
```yaml
90+
llm:
91+
enabled: true
92+
provider: openai
93+
apiKey: ${QIRREL_LLM_API_KEY}
94+
model: gpt-4o-mini
95+
timeout: 30000
96+
cacheTtl: 300000
97+
```
6198
62-
const pipeline = new Pipeline();
99+
## Quality Gates (CI/CD)
63100
64-
if (pipeline.isCached('some text')) {
65-
console.log(pipeline.getCached('some text'));
66-
} else {
67-
const result = await pipeline.process('some text');
68-
console.log(result.data?.entities);
69-
}
70-
```
101+
This repository includes GitHub Actions workflows:
102+
103+
- `ci.yml`: runs install, build, tests, and coverage on push/PR.
104+
- `release.yml`: runs release checks and can publish to npm on version tags (`v*`) when `NPM_TOKEN` is configured.
71105

72106
## Documentation
73107

74-
- [API Reference](./docs/api.md)
75-
- [Configuration Guide](./docs/configuration.md)
76-
- [Usage Examples](./docs/examples.md)
77-
- [Basic Usage](./docs/usage/basic.md)
78-
- [LLM Integration](./docs/integrations/llm.md)
79-
- [Pipeline Events](./docs/events.md)
80-
- [Caching](./docs/usage/caching.md)
108+
- [Docs Home (Styled)](./docs/index.html)
109+
- [API Reference](./docs/pages/api.html)
110+
- [Configuration Guide](./docs/pages/configuration.html)
111+
- [Usage Examples](./docs/pages/examples.html)
112+
- [Basic Usage](./docs/pages/basic.html)
113+
- [Caching](./docs/pages/caching.html)
114+
- [Pipeline Events](./docs/pages/events.html)
115+
- [LLM Integration](./docs/pages/llm.html)
116+
- [Architecture Walkthrough](./docs/pages/walkthrough.html)
117+
118+
Markdown source docs are still available under `./docs/`.
81119

82120
## Contributing
83121

‎docs/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Qirrel Docs Site
2+
3+
Open `docs/index.html` for the styled docs experience with custom classes, spacing utilities, and motion.
4+
5+
Legacy markdown docs remain in this folder for source/reference compatibility.

0 commit comments

Comments
 (0)