File size: 4,684 Bytes
c8016f6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2f024ae
 
 
c8016f6
 
 
 
2f024ae
 
 
 
c8016f6
 
 
 
 
 
 
 
 
 
 
 
2f024ae
 
 
 
c8016f6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
# 05 - Debugging Common Problems

This guide lists common failures and what to check first.

## The Website Does Not Load

Check Hugging Face logs:

```text
Hugging Face Space -> Logs
```

Common causes:

- Build failed.
- Missing dependency in `requirements.txt`.
- Python syntax error.
- Missing required file.
- Space is still rebuilding.

CLI check:

```bash
hf spaces info UWRFR/UWaterlooRFRChatBot
```

If the Space is building, wait and refresh.

## Ask Tab Fails with an LLM Error

Common messages:

```text
credit balance is too low
ANTHROPIC_API_KEY is not set
OPENAI_API_KEY is not set
APIConnectionError
invalid_api_key
```

Check:

- The correct key exists in Hugging Face secrets.
- The key has credits.
- The app is configured for the provider you expect.
- The Space was restarted after changing secrets.

If Anthropic credits are unavailable, switch the app to OpenAI only if
`OPENAI_API_KEY` is available and configured.

## New Case Study Request Upload Fails

The request tab uploads to Google Drive using:

```text
GOOGLE_OAUTH_CLIENT_ID
GOOGLE_OAUTH_CLIENT_SECRET
GOOGLE_OAUTH_REFRESH_TOKEN
```

Check:

- The three OAuth secrets exist in Hugging Face.
- The refresh token was generated by signing in as the Google account that
  should own uploaded request folders, usually `rfr.rag.uwaterloo@gmail.com`.
- The intake folder is owned by or shared with that Google account.
- The intake folder ID is correct:

```text
10n_-uOCT2GXu_G3r1qi5qJr8hHoy-E_y
```

If using a different folder, set:

```text
RFR_REQUESTS_DRIVE_FOLDER_ID
```

If the error says service accounts do not have storage quota, the app is falling
back to `GOOGLE_SERVICE_ACCOUNT_JSON`. Add the OAuth secrets above, or move the
intake folder to a Google Shared Drive.

## New Case Does Not Appear in Case Studies

Usually one of these files was not rebuilt or committed:

```text
data/extracted/CSxx.json
data/extracted/case_summaries.json
data/extracted/precomputed_embeddings.json
```

Run:

```bash
python3 ingest/ingest_pipeline_outputs.py --case-id CSxx
python3 ingest/create_summary_chunks.py
python3 ingest/embed_and_index.py
```

Then commit and push the changed files.

## Case Appears but Sources Are Missing

The Case Studies tab reads source links from each case's `source_links` field in
`data/extracted/CSxx.json`.

Source links come from:

- `sources.txt`
- `sources.json`
- `dois.txt`
- `ingest/source_link_overrides.json`

Fix:

1. Add APA-style links to `ingest/source_link_overrides.json`.
2. Re-run:

```bash
python3 ingest/ingest_pipeline_outputs.py --case-id CSxx --force
python3 ingest/create_summary_chunks.py
python3 ingest/embed_and_index.py
```

3. Commit and push.

## Case Summary Looks Wrong

Check the canonical Ver2 memo:

```text
data/raw/CSxx/pipeline_output/CSxx_Ver2.md
```

If the wrong paper was processed, replace the source files in:

```text
data/raw/CSxx/
```

Then rerun:

```bash
python3 -m case_study_pipeline.run_case_study \
  --case-folder data/raw/CSxx \
  --case-id CSxx \
  --llm-provider claude \
  --max-chars-per-source 150000 \
  --force
```

Then select, ingest, summarize, and embed:

```bash
python3 -m case_study_pipeline.select_best_run --case-id CSxx
python3 ingest/ingest_pipeline_outputs.py --case-id CSxx --force
python3 ingest/create_summary_chunks.py
python3 ingest/embed_and_index.py
```

## Hugging Face Shows Old Content

Check the deployed commit:

```bash
hf spaces info UWRFR/UWaterlooRFRChatBot
```

Compare the `sha` with:

```bash
git log --oneline -5
```

If the Hugging Face SHA is old, push again:

```bash
git push uwrfr-chatbot HEAD:main
```

## Git Push Fails

Check remotes:

```bash
git remote -v
```

Expected remotes:

```text
shared-github https://github.com/rfrraguwaterloo-cmyk/UWaterlooManagedRetreatChatbot.git
uwrfr-chatbot https://huggingface.co/spaces/UWRFR/UWaterlooRFRChatBot
```

If authentication fails:

- For GitHub, sign in with GitHub credentials or a GitHub token.
- For Hugging Face, run:

```bash
hf auth login --add-to-git-credential
```

Use a Hugging Face token with write access to the Space.

## Drive Pipeline Output Upload Fails

The extraction pipeline can still run locally even if Drive output uploads fail.

Common warning:

```text
[Drive] Warning: could not initialize uploader
Drive uploads will be skipped for this run.
```

This means the local files were created, but the PDF outputs were not uploaded
to Drive.

Check:

- `GOOGLE_CREDENTIALS_FILE` points to an OAuth client credential file.
- Your browser completed Google login.
- The target case folder exists in `case_study_pipeline/drive_folders.json`.
- The Google account has permission to write to the Drive folder.