Skip to content

Commit fdeddff

Browse files
lukeroantreeONSrileyok-ons
lukeroantreeONS
and
rileyok-ons
authored
docs(quarto): Tidy up & address Quarto-rendered formatting for first Pages deployment (#148)
* docs(quarto): changes to Custom Hooks Demo notebook as per Excel spreadsheet - row 7 * docs(servers): changes to documentation as per Excel spreadsheet - row 15 * docs(indexers): changes to indexers documentation as per Excel spreadsheet - rows 11-14 (note, some issues not addressed) * docs(vectorisers): changes to vectorisers documentation as per Excel spreadsheet - rows 8-10 * docs(demo): remove install instructions from the custom vectoriser demo * docs(demo): remove install instructions from general demo * docs(demos): changes to DEMOs README documentation as per Excel spreadsheet - row 4 * docs(landing page): changes to Landing Page documentation as per Excel spreadsheet - row 2 * docs(quarto): address Riley's Comments * docs(quarto): add ONS site icon * docs(quarto): address Erlend's Comments * docs(quarto): address Riley's Comments, round 2 * docs(quarto): address Riley's Comments, round 3 * docs(quarto): address Riley's Comments, round 4 * docs(quarto): address Riley's Comments, round 5 - DEMO installation order emphasis * docs(quarto): missed code quotes on error in servers * docs(quarto): address Riley's Comments, round 6 - embed() return formatting * docs(quarto): address Erlend's Comments, round 2 - indexers overview * added more highlights * even more highlighting --------- Co-authored-by: rileyok-ons <205916635+rileyok-ons@users.noreply.github.com>
1 parent 3c1164d commit fdeddff

17 files changed

Lines changed: 319 additions & 516 deletions

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ repos:
4848
name: deptry (uv)
4949
language: system
5050
pass_filenames: false # deptry expects a project path, not filenames
51-
entry: uv run deptry .
51+
entry: uv run deptry --per-rule-ignores "DEP003=plum,DEP004=quartodoc|numpydoc" .
5252

5353
- id: forbid-new-init
5454
name: Check if __init__.py is added to the src folder

‎DEMO/README.md‎

Lines changed: 89 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,14 @@
1-
# Demo for `classifai`
1+
# Overview of Demonstrations & Examples
22

33
This directory contains a set of Jupyter notebooks designed to help you understand and use `classifai` effectively.
44

5-
## Prerequisites
6-
7-
You may wish to download each notebook individually and the demo dataset individually - each notebook contains specific installation instructions on how to set up an environemnt and download the package
8-
9-
## Running the Demo
10-
11-
To start the demo, launch Jupyter Notebook or JupyterLab from your terminal in this directory:
12-
13-
```bash
14-
jupyter notebook
15-
```
16-
17-
Or, if you prefer JupyterLab:
18-
19-
```bash
20-
jupyter lab
21-
```
22-
23-
Then, open the notebooks in your browser.
24-
We recommend going through the the `general_workflow_demo.ipynb` notebook for a broad overview of the package before moving onto the `custom_vectoriser.ipynb` notebook, which covers a more advanced use-case.
5+
---
256

267
## Notebooks Overview
278

28-
This demo includes two Jupyter notebooks:
9+
This demo series includes several Jupyter notebooks:
2910

30-
### 1. `general_workflow_demo.ipynb`
11+
### 1. ✨ ClassifAI Demo - Introduction & Basic Usage ✨ : `general_workflow_demo.ipynb`
3112

3213
This introduces the core features of `classifai`.
3314

@@ -43,7 +24,7 @@ It covers:
4324

4425
This notebook is intended for prospective users to get a quick overview of what the package can do, and as a 'jumping off point' for new projects.
4526

46-
### 2. `custom_vectoriser.ipynb`
27+
### 2. Creating Your Own Vectoriser : `custom_vectoriser.ipynb`
4728

4829
This notebook demonstrates how to create a new, custom Vectoriser by extending the base `VectoriserBase` class.
4930

@@ -55,7 +36,7 @@ It covers:
5536

5637
This notebook is for users who want to implement a vectorisation approach not covered by our existing suite of Vectorisers.
5738

58-
### 3. `custom_preprocessing_and_postprocessing_hooks.ipynb`
39+
### 3. VectorStore pre- and post- processing logic with _Hooks_ 🪝 : `custom_preprocessing_and_postprocessing_hooks.ipynb`
5940

6041
This notebook demostrates how to add custom Python code logic to the VectorStore search pipeline, such as performing spell checking on user input, without breaking the data flow of the ClassifAI VectorStore.
6142

@@ -70,3 +51,86 @@ It covers:
7051
* Examples of different kinds of hooks that can be written - [spellchecking, deduplicating results, adding extra info to results based on result ids]
7152

7253
---
54+
55+
## Installation of classifai
56+
57+
#### *0)* [optional] Create and activate a virtual environment from the command line
58+
59+
##### Using pip + venv
60+
61+
Create a virtual environment:
62+
63+
`python -m venv .venv`
64+
65+
##### Using UV
66+
67+
Create a virtual environment:
68+
69+
`uv venv`
70+
71+
##### Activating your environment
72+
73+
(macOS / Linux):
74+
75+
`source .venv/bin/activate`
76+
77+
Activate it (Windows):
78+
79+
`source .venv/Scripts/activate`
80+
81+
#### *1)* Install the classifai package
82+
83+
##### Using pip
84+
85+
`pip install "https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl"`
86+
87+
##### Using uv
88+
89+
one-off:
90+
91+
`uv pip install "https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl"`
92+
93+
add as project dependency:
94+
95+
`uv add "https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl"`
96+
97+
98+
#### *2)* Install optional dependencies
99+
100+
##### Using pip
101+
102+
`pip install "classifai[<dependency>]"`
103+
104+
where `<dependency>` is one or more of `huggingface`,`gcp`,`ollama`, or `all` to install all of them.
105+
##### Using uv
106+
107+
one-off installation
108+
109+
`uv pip install "classifai[<dependency>]"`
110+
111+
add as project dependency
112+
113+
`uv add "classifai[<dependency>]"`
114+
115+
---
116+
117+
## Prerequisites
118+
119+
You may wish to download each notebook individually and the demo dataset individually - each notebook contains specific installation instructions on how to set up an environemnt and download the package
120+
121+
## Running the Demo
122+
123+
To start the demo, launch Jupyter Notebook or JupyterLab from your terminal in this directory:
124+
125+
```bash
126+
jupyter notebook
127+
```
128+
129+
Or, if you prefer JupyterLab:
130+
131+
```bash
132+
jupyter lab
133+
```
134+
135+
Then, open the notebooks in your browser.
136+
We recommend going through the the `general_workflow_demo.ipynb` notebook for a broad overview of the package before moving onto the `custom_vectoriser.ipynb` notebook, which covers a more advanced use-case.

‎DEMO/custom_preprocessing_and_postprocessing_hooks.ipynb‎

Lines changed: 14 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,12 @@
7171
"The use of these dataclasses both helps the user of the package to understand what data needs to be provided to the Vectorstore and how a user should interact with the objects being returned by these VectorStore functions. Additionally, this ensures robustness of the package by checking that the correct columns are present in the data before operating on it. \n",
7272
"\n",
7373
"The reverse_search() and embed() VectorStore functions have their own input and output data classes with their own validity column data checks. The names of each set are intuitively:\n",
74-
"| **VectorStore Method** | **Input Dataclass** | **Output Dataclass** |\n",
74+
"\n",
75+
"| **VectorStore Method** | **Input Dataclass** | **Output Dataclass** |\n",
7576
"|-------------------------------|-----------------------------|-----------------------------|\n",
76-
"| `VectorStore.search()` | `VectorStoreSearchInput` | `VectorStoreSearchOutput` |\n",
77+
"| `VectorStore.search()` | `VectorStoreSearchInput` | `VectorStoreSearchOutput` |\n",
7778
"| `VectorStore.reverse_search()` | `VectorStoreReverseSearchInput` | `VectorStoreReverseSearchOutput` |\n",
78-
"| `VectorStore.embed()` | `VectorStoreEmbedInput` | `VectorStoreEmbedOutput` |\n",
79+
"| `VectorStore.embed()` | `VectorStoreEmbedInput` | `VectorStoreEmbedOutput` |\n",
7980
"\n",
8081
"Users of the package can use the schema of each of these input and output dataclasses to understand how to interface with these main methods of the VectorStore class.\n",
8182
"\n"
@@ -145,92 +146,9 @@
145146
"cell_type": "markdown",
146147
"metadata": {},
147148
"source": [
148-
"### Installation (pre-release)\n",
149-
"\n",
150-
"`Classifai` is currently in **pre-release** and is **not yet published on PyPI**. \n",
151-
"This section describes how to install the packaged **wheel** from the project’s public GitHub Releases so that you can follow through this DEMO and try the code yourself.\n",
152-
"\n",
153-
"#### 1) Create and activate a virtual environment in command line\n",
154-
"\n",
155-
"##### Using `pip` + `venv`\n",
156-
"Create a virtual environment:\n",
157-
"\n",
158-
"```bash\n",
159-
"python -m venv .venv\n",
160-
"```\n",
161-
"\n",
162-
"##### Using `UV`\n",
163-
"Create a virtual environment:\n",
164-
"\n",
165-
"```bash\n",
166-
"uv venv\n",
167-
"```\n",
168-
"\n",
169-
"Activate the created environment with \n",
170-
"\n",
171-
"(macOS / Linux):\n",
172-
"```bash\n",
173-
"source .venv/bin/activate\n",
174-
"```\n",
175-
"Activate it (Windows):\n",
176-
"```bash\n",
177-
"source .venv/Scripts/activate\n",
178-
"```\n",
179-
"\n",
180-
"---\n",
181-
"\n",
182-
"#### 2) Install the pre-release wheel\n",
183-
"\n",
184-
"##### Using `pip`\n",
185-
"```bash\n",
186-
"pip install \"https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl\"\n",
187-
"```\n",
188-
"\n",
189-
"##### Using `uv`\n",
190-
"```bash\n",
191-
"uv pip install \"https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl\"\n",
192-
"```\n",
193-
"\n",
194149
"---\n",
195150
"\n",
196-
"#### 3) Install optional dependencies (`[huggingface]`)\n",
197-
"\n",
198-
"Finally, for this demo we will be using the Huggingface Library to download embedding models - we therefore need an optional dependency of the Classifai Pacakge:\n",
199-
"\n",
200-
"##### Using `pip`\n",
201-
"```bash\n",
202-
"pip install \"classifai[huggingface]\"\n",
203-
"```\n",
204-
"\n",
205-
"##### Using `uv pip`\n",
206-
"```bash\n",
207-
"uv pip install \"classifai[huggingface]\"\n",
208-
"```"
209-
]
210-
},
211-
{
212-
"cell_type": "code",
213-
"execution_count": null,
214-
"metadata": {},
215-
"outputs": [],
216-
"source": [
217-
"# Assuming the step one virtual environemnt is set up and actiavted and ready in the terminal, run the following commands to install the classifai package and the huggingface dependencies.\n",
218-
"## PIP\n",
219-
"#!pip install \"https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl\"\n",
220-
"#!pip install \"classifai[huggingface]\"\n",
221-
"\n",
222-
"## UV\n",
223-
"#!uv pip install \"https://github.com/datasciencecampus/classifai/releases/download/v0.2.1/classifai-0.2.1-py3-none-any.whl\"\n",
224-
"#!uv pip install \"classifai[huggingface]\"\n"
225-
]
226-
},
227-
{
228-
"cell_type": "markdown",
229-
"metadata": {},
230-
"source": [
231-
"##### Note! :\n",
232-
"\n",
233-
"You may need to install the ipykernel python package to run Notebook cells with your Python environment"
151+
"#### If you can run the following cell in this notebook, you should be good to go!"
234152
]
235153
},
236154
{
@@ -239,29 +157,20 @@
239157
"metadata": {},
240158
"outputs": [],
241159
"source": [
242-
"#!pip install ipykernel\n",
160+
"from classifai.vectorisers import HuggingFaceVectoriser\n",
243161
"\n",
244-
"#!uv pip install ipykernel"
162+
"print(\"done!\")"
245163
]
246164
},
247165
{
248166
"cell_type": "markdown",
249167
"metadata": {},
250168
"source": [
251-
"---\n",
252-
"\n",
253-
"#### If you can run the following cell in this notebook, you should be good to go!"
254-
]
255-
},
256-
{
257-
"cell_type": "code",
258-
"execution_count": null,
259-
"metadata": {},
260-
"outputs": [],
261-
"source": [
262-
"from classifai.vectorisers import HuggingFaceVectoriser\n",
169+
"#### Alternatively, to test without running a notebook, run the following from your command line; \n",
263170
"\n",
264-
"print(\"done!\")"
171+
"```shell\n",
172+
"python -c \"import classifai\"\n",
173+
"```"
265174
]
266175
},
267176
{
@@ -761,7 +670,7 @@
761670
],
762671
"metadata": {
763672
"kernelspec": {
764-
"display_name": "classifai",
673+
"display_name": "Python 3 (ipykernel)",
765674
"language": "python",
766675
"name": "python3"
767676
},
@@ -775,9 +684,9 @@
775684
"name": "python",
776685
"nbconvert_exporter": "python",
777686
"pygments_lexer": "ipython3",
778-
"version": "3.13.7"
687+
"version": "3.12.10"
779688
}
780689
},
781690
"nbformat": 4,
782-
"nbformat_minor": 2
691+
"nbformat_minor": 4
783692
}

0 commit comments

Comments
 (0)