File size: 23,656 Bytes
891fe52
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
# Polyhedra User Guide

Complete guide to using Polyhedra MCP Server for academic research.

## Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [IDE Setup](#ide-setup)
- [Core Concepts](#core-concepts)
- [Using the Tools](#using-the-tools)
- [Research Workflows](#research-workflows)
- [Tips & Best Practices](#tips--best-practices)
- [Troubleshooting](#troubleshooting)

---

## Quick Start

**Get started in 3 steps:**

1. **Install Polyhedra**
   ```bash
   git clone https://github.com/yourusername/polyhedra.git
   cd polyhedra
   pip install -e .
   ```

2. **Configure Your IDE** (example for Cursor)
   
   Add to ~/.cursor/mcp.json:
   ```json
   {
     "mcpServers": {
       "polyhedra": {
         "command": "python",
         "args": ["-m", "polyhedra.server"]
       }
     }
   }
   ```

3. **Start Using**
   
   Open your IDE and ask:
   `
   "Initialize a new research project called 'deep-learning-review'"
   `

---

## Installation

### Requirements

- Python 3.11 or higher
- Git
- One of the supported IDEs:
  - Cursor
  - VS Code with GitHub Copilot
  - Windsurf
  - VS Code with MCP extension

### Method 1: Standard Installation

```bash
git clone https://github.com/yourusername/polyhedra.git
cd polyhedra
pip install -e .
```

### Method 2: Using uv (faster)

```bash
git clone https://github.com/yourusername/polyhedra.git
cd polyhedra
pip install uv
uv pip install -e .
```

### Verify Installation

```bash
python -m polyhedra.server --version
```

---

## IDE Setup

### Cursor

1. **Open MCP Settings**: ~/.cursor/mcp.json

2. **Add Polyhedra**:
   ```json
   {
     "mcpServers": {
       "polyhedra": {
         "command": "python",
         "args": ["-m", "polyhedra.server"]
       }
     }
   }
   ```

3. **Restart Cursor**

4. **Test**: Ask Copilot "What Polyhedra tools are available?"

### VS Code with GitHub Copilot

1. **Create workspace settings**: .vscode/settings.json

2. **Add configuration**:
   `json
   {
     "github.copilot.chat.codeGeneration.instructions": [
       {
         "file": ".github/copilot-instructions.md"
       }
     ]
   }
   `

3. **Create instructions file**: .github/copilot-instructions.md
   `markdown
   Use the Polyhedra MCP tools for academic research tasks.
   Available tools: search_papers, add_citation, index_papers, etc.
   `

4. **Reload window**: Ctrl+Shift+P  "Developer: Reload Window"

### Windsurf

Same as Cursor, but use ~/.windsurf/mcp.json

### VS Code with MCP Extension

1. Install MCP extension from marketplace
2. Configure in workspace settings
3. Point to uvx --from polyhedra polyhedra

For detailed setup instructions, see docs/SETUP.md

---

## Core Concepts

### Project Structure

Polyhedra expects this directory structure:

`
my-research-project/
 literature/          # Research papers (JSON, PDF)
 references.bib       # BibTeX citations
 writing/            # Your papers and drafts
 ideas/              # Notes and brainstorming
 data/               # Research data
 .poly/              # Polyhedra metadata (auto-created)
     embeddings/     # Semantic search index
`

### Semantic Search (RAG)

Polyhedra uses **RAG (Retrieval Augmented Generation)** to find relevant papers:

1. **Index papers**  Creates embeddings from titles and abstracts
2. **Query with natural language**  Finds semantically similar papers
3. **Get ranked results**  Papers sorted by relevance score

### Citation Management

- **BibTeX format** for all citations
- **Automatic deduplication** by citation key
- **Auto-generated keys** from author/year/title
- **Stored in** 
eferences.bib

---

## Using the Tools

### 1. Initialize Project

**What it does**: Creates standard research project structure

**When to use**: Starting a new research project

**Example**:
`
"Initialize a new research project called 'transformer-survey'"
`

**Creates**:
- 5 directories (literature, writing, ideas, data, notes)
- 2 files (README.md, references.bib)

---

## Literature Review Generation (v2.1) 🆕

Generate AI-powered literature reviews from your paper collection.

### Prerequisites

1. **Papers collected** via `search_papers` or manual JSON file
2. **LLM API key configured** (see [Setup Guide](SETUP.md))
   - Anthropic (recommended): `export ANTHROPIC_API_KEY=sk-ant-...`
   - OpenAI (alternative): `export OPENAI_API_KEY=sk-...`

### Basic Workflow

#### Step 1: Search and Collect Papers

```
"Search for 50 papers on transformer efficiency techniques"
```

Papers automatically saved to `literature/papers.json`

#### Step 2: Estimate Cost (Recommended)

```
"Estimate cost for reviewing these 50 papers with standard depth"
```

Returns: `{"estimated_usd": 0.15, "paper_count": 50, "depth": "standard"}`

#### Step 3: Generate Review

```
"Generate a literature review from my papers focused on mobile deployment"
```

Generates:
- `literature/review.md` - Structured academic review
- Auto-adds all citations to `references.bib`
- Returns metadata and actual cost

#### Step 4: Review and Refine

Open `literature/review.md` to see:
- ✅ **Overview**: Field introduction and scope
- ✅ **Taxonomy**: Hierarchical organization of approaches
- ✅ **Critical Analysis**: Strengths, weaknesses, comparisons
- ✅ **Research Gaps**: Underexplored areas and opportunities
- ✅ **Conclusion**: Summary and future directions
- ✅ **Proper Citations**: All papers cited as `[Author et al., Year]`

### Review Depth Levels

Choose the right depth for your use case:

#### Brief (~650 words, 2-3 pages)
**Best for**: Quick overviews, presentation prep, initial exploration

```
"Generate a brief literature review"
```

**Output**:
- High-level overview
- Major themes only
- 5-10 minute read
- **Cost**: $0.05-0.12 (50 papers)

#### Standard (~2000 words, 5-8 pages)
**Best for**: Paper background sections, grant proposals, comprehensive understanding

```
"Generate a standard literature review"
```

**Output**:
- Comprehensive coverage
- Detailed taxonomy
- Critical analysis
- Research gaps section
- 20-30 minute read
- **Cost**: $0.12-0.25 (50 papers)

#### Comprehensive (~2500 words, 10-15 pages)
**Best for**: Dissertation chapters, major survey papers, formal publications

```
"Generate a comprehensive literature review"
```

**Output**:
- Exhaustive review
- Deep analysis of each approach
- Extensive gaps section
- Methodology comparison
- 45-60 minute read
- **Cost**: $0.20-0.40 (50 papers)

### Review Structure Types

Choose how to organize your review:

#### Thematic (Default)
Groups papers by research themes and approaches.

```
"Generate a thematic literature review"
```

**Best for**: Understanding the landscape, identifying main directions

**Example sections**:
- Attention Mechanisms
- Efficiency Techniques
- Mobile Architectures
- Quantization Methods

#### Chronological
Orders papers by publication timeline.

```
"Generate a chronological literature review"
```

**Best for**: Tracking field evolution, understanding historical context

**Example sections**:
- Early Work (2017-2019)
- Breakthrough Period (2020-2021)
- Recent Advances (2022-2024)

#### Methodological
Organizes by research methods used.

```
"Generate a methodological literature review"
```

**Best for**: Comparing approaches, identifying methodology gaps

**Example sections**:
- Neural Architecture Search
- Knowledge Distillation
- Pruning and Quantization
- Hardware-Aware Design

### Advanced Usage

#### Focused Review
Narrow the scope to specific aspects:

```
"Generate a comprehensive review focused on quantization techniques for edge devices"
```

The `focus` parameter helps the LLM:
- Prioritize relevant papers
- Emphasize specific aspects
- Filter out tangential content
- Provide deeper analysis of focus area

#### Custom Output Location

```
"Generate a review and save to method/related-work.md"
```

#### Specific Model Selection

```
"Generate review using GPT-4 Turbo"
```

Available models:
- `claude-3-5-sonnet-20241022` (default, recommended)
- `claude-3-opus-20240229` (higher quality, higher cost)
- `gpt-4o` (OpenAI default)
- `gpt-4-turbo` (OpenAI alternative)

#### Skip Research Gaps

```
"Generate a brief review without research gaps section"
```

Useful when you only need synthesis, not gap analysis.

### Cost Management

#### Always Estimate First

For large collections or expensive depths:

```
"Estimate cost before generating a comprehensive review of 100 papers"
```

Returns detailed cost breakdown before spending credits.

#### Understanding Cost Warnings

If estimated cost > $0.10, Polyhedra will warn you:

```
⚠️ Estimated cost: $0.25 for comprehensive review of 75 papers
Add confirm_cost=true to proceed
```

To proceed:
```
"Generate the review with confirm_cost=true"
```

#### Budget Limits

Default maximum cost: **$1.00 per operation**

To change:
```bash
export POLYHEDRA_MAX_COST=0.50  # Set lower limit
```

Polyhedra will block operations exceeding the limit.

To override (not recommended):
```
"Generate the review with force=true"
```

#### Tracking Costs

Each generation returns actual cost:

```json
{
  "cost": {
    "input_tokens": 18234,
    "output_tokens": 5890,
    "total_tokens": 24124,
    "total_usd": 0.14
  }
}
```

### Tips & Best Practices

#### 1. Start Small
Begin with brief reviews to understand output quality:
```
"Generate a brief review to see the format first"
```

#### 2. Curate Papers
**Better input = Better output**

Ideal paper count: **20-50 papers**
- Too few (<10): Shallow analysis
- Just right (20-50): Comprehensive but manageable
- Too many (>100): May hit token limits or high costs

#### 3. Use Focus Parameter
Narrow scope improves relevance:
```
"Generate review focused on real-time inference optimization"
```

#### 4. Check Cost for Large Collections
Always estimate for >50 papers:
```
"Estimate cost first for 80 papers"
```

#### 5. Iterate Depth Levels
Progressive refinement:
1. Start with `brief` for quick overview
2. Expand to `standard` for more detail
3. Use `comprehensive` only for formal publications

#### 6. Manual Refinement
Generated reviews are **starting points**:
- Review for accuracy
- Add domain-specific insights
- Verify citations against source papers
- Refine structure to match your needs

#### 7. Combine with Search
Iterative workflow:
```
1. "Search for initial papers on topic X"
2. "Generate brief review"
3. "Based on gaps, search for papers on Y"
4. "Add new papers to literature/papers.json"
5. "Generate updated standard review"
```

### Common Issues

#### "LLM service not configured"

**Cause**: Missing API key

**Solution**:
```bash
# Choose one:
export ANTHROPIC_API_KEY=sk-ant-your-key
export OPENAI_API_KEY=sk-your-key

# Restart IDE
```

Verify:
```
"Check if my LLM configuration is working"
```

#### "Papers file not found"

**Cause**: No papers.json exists

**Solution**:
```
"Search for papers first, then generate review"
```

Or manually create `literature/papers.json`:
```json
[
  {
    "title": "Paper Title",
    "authors": [{"name": "Author Name"}],
    "year": 2024,
    "abstract": "Paper abstract...",
    "venue": "Conference Name"
  }
]
```

#### "Papers file is empty"

**Cause**: Empty JSON array `[]`

**Solution**:
```
"Search for papers to populate the file"
```

#### "Cost exceeds configured limit"

**Cause**: Estimated cost > `POLYHEDRA_MAX_COST`

**Solutions**:
1. Increase limit: `export POLYHEDRA_MAX_COST=1.50`
2. Reduce paper count (filter to most relevant)
3. Use brief depth instead of comprehensive
4. Force execution: Add `force=true` (not recommended)

#### "Review quality insufficient"

**Causes & Solutions**:

**Too generic**:
- Add specific focus parameter
- Curate papers more carefully
- Try different structure type

**Missing key papers**:
- Verify papers.json includes them
- Check citation coverage in metadata

**Poor organization**:
- Try different structure (thematic vs chronological)
- Add focus to narrow scope

**Shallow analysis**:
- Upgrade from brief to standard/comprehensive
- Reduce paper count for deeper analysis

#### "Token limit exceeded"

**Cause**: Too many papers for context window

**Solutions**:
1. Reduce paper count (aim for <75)
2. Use brief depth (less output tokens)
3. Split into multiple focused reviews

### Cost Examples (Real Scenarios)

| Scenario | Papers | Depth | Cost | Time |
|----------|--------|-------|------|------|
| Conference presentation prep | 20 | brief | $0.06 | 1-2 min |
| Paper background section | 40 | standard | $0.14 | 2-3 min |
| PhD qualifying exam | 60 | comprehensive | $0.28 | 3-4 min |
| Grant proposal literature review | 50 | standard | $0.18 | 2-3 min |
| Dissertation chapter | 80 | comprehensive | $0.42 | 4-5 min |
| Survey paper | 100 | comprehensive | $0.55 | 5-6 min |

*Costs are estimates for Anthropic Claude Sonnet. GPT-4 Turbo costs ~2.5x more.*

---

### 2. Search Papers

**What it does**: Searches Semantic Scholar for academic papers

**When to use**: Literature review, finding related work

**Example**:
`
"Search for recent papers on 'attention mechanisms in transformers' 
 published between 2020-2023, limit to 10 results"
`

**Parameters**:
- query: Search terms (required)
- limit: Max results (default: 10, max: 100)
- year_start: Filter by year (optional)
- year_end: Filter by year (optional)

**Returns**: Paper details with titles, authors, abstracts, citations, BibTeX

---

### 3. Get Paper Details

**What it does**: Gets detailed info for a specific paper by ID

**When to use**: Following up on a specific paper

**Example**:
`
"Get details for paper ID 204e3073870fae3d05bcbc2f6a8e263d9b72e776"
`

**Returns**: Full paper metadata, BibTeX entry, citation count

---

### 4. Add Citation

**What it does**: Adds a BibTeX entry to references.bib

**When to use**: Building your bibliography

**Example**:
`
"Add this citation to my bibliography:
@article{vaswani2017attention,
  title={Attention is all you need},
  author={Vaswani, Ashish and Shazeer, Noam},
  year={2017}
}"
`

**Features**:
- Automatic deduplication
- Validates BibTeX format
- Returns citation key for use in writing

---

### 5. Get Citations

**What it does**: Lists all citations in your bibliography

**When to use**: Reviewing your references, checking what's already added

**Example**:
`
"Show me all my citations"
`

**Returns**: Array of all BibTeX entries with keys

---

### 6. Index Papers

**What it does**: Creates semantic search index from saved papers

**When to use**: After collecting papers, before querying

**Example**:
`
"Index the papers in literature/recent-papers.json"
`

**Requirements**: Papers file must exist with title and abstract fields

**Performance**: ~2 seconds for 50 papers

---

### 7. Query Similar Papers

**What it does**: Semantic search over indexed papers

**When to use**: Finding relevant papers in your collection

**Example**:
`
"Find papers similar to 'self-attention mechanisms for NLP' 
 from my indexed papers, show top 5"
`

**Parameters**:
- query: Natural language search (required)
- k: Number of results (default: 5)

**Returns**: Papers ranked by relevance score (0.0-1.0)

**Requires**: Papers must be indexed first

---

### 8. Save File

**What it does**: Writes content to a file in your project

**When to use**: Saving generated content, creating drafts

**Example**:
`
"Save this abstract to writing/draft-abstract.md:
[your abstract text]"
`

**Features**:
- Creates parent directories automatically
- Supports append mode
- UTF-8 encoding

---

### 9. Get Context

**What it does**: Reads files from your project

**When to use**: Reviewing content, including context in prompts

**Example**:
`
"Read the contents of writing/introduction.md and ideas/key-points.md"
`

**Features**:
- Batch reading (multiple files at once)
- Reports missing files without failing
- UTF-8 decoding

**Returns**: Dictionary of file contents + list of missing files

---

### 10. Get Project Status

**What it does**: Overview of your research project

**When to use**: Checking progress, understanding project state

**Example**:
`
"Give me the status of my research project"
`

**Returns**:
- Paper count in literature/
- Citation count in references.bib
- RAG index status
- List of standard files
- Total file count

---

## Research Workflows

### Workflow 1: Literature Review

**Goal**: Find and organize relevant papers

`
1. "Initialize a project called 'literature-review-transformers'"

2. "Search for papers on 'transformer architecture' from 2017-2023, 
    limit 20"

3. "Save those papers to literature/transformer-papers.json"

4. "Add citations for the top 5 papers to my bibliography"

5. "Index the papers in literature/transformer-papers.json"

6. "Find papers similar to 'positional encoding in transformers'"

7. "Get project status"
`

**Result**: Organized collection of papers with citations ready for writing

---

### Workflow 2: Writing with Citations

**Goal**: Draft a paper section with proper citations

`
1. "Search for papers on 'BERT pretraining' and add the top 3 
    to my citations"

2. "Show me all my citations"

3. "Save this introduction to writing/intro.md:
    [AI generates introduction with citation keys]"

4. "Read writing/intro.md to verify"
`

**Result**: Draft with citation keys that match references.bib

---

### Workflow 3: Finding Research Gaps

**Goal**: Identify under-explored areas

`
1. "Search for 'multimodal transformers' papers from 2020-2023"

2. "Save to literature/multimodal.json and index them"

3. "Query for papers about 'video understanding transformers'"

4. "Query for papers about 'audio-visual fusion'"

5. "Compare the results to find gaps"
`

**Result**: Understand coverage of different topics in your collection

---

### Workflow 4: Related Work Section

**Goal**: Build comprehensive related work

`
1. "Search for papers on [my topic] and save to literature/related.json"

2. "Index literature/related.json"

3. "For each subsection topic, query similar papers"

4. "Add relevant citations to references.bib"

5. "Save organized related work to writing/related-work.md"
`

**Result**: Well-organized related work section with citations

---

## Tips & Best Practices

### Search Strategies

 **DO**:
- Use specific technical terms: "attention mechanisms" vs "AI"
- Combine concepts: "BERT pretraining methodology"
- Filter by year for recent work: year_start=2020
- Start with small limits (5-10) and expand

 **DON'T**:
- Use overly broad terms: "machine learning"
- Request too many results at once (API rate limits)
- Search without year filters when recency matters

### Citation Management

 **DO**:
- Let Polyhedra generate citation keys automatically
- Review citations before adding to bibliography
- Use consistent citation styles
- Check for duplicates with "Show me all my citations"

 **DON'T**:
- Manually create citation keys (error-prone)
- Add same paper twice (auto-dedup handles this)
- Mix citation formats (stick to BibTeX)

### Semantic Search

 **DO**:
- Index papers before querying
- Re-index when adding new papers to collection
- Use natural language queries: "papers about X"
- Check relevance scores (>0.7 is high relevance)

 **DON'T**:
- Query before indexing (returns empty results)
- Use too many keywords (semantic search handles concepts)
- Ignore low relevance scores (<0.3)

### File Organization

 **DO**:
- Keep papers in literature/ directory
- Name files descriptively: 	ransformer-papers-2023.json
- Use subdirectories: literature/attention/, literature/pretraining/
- Back up your 
eferences.bib file

 **DON'T**:
- Store papers in random locations
- Use generic names: papers.json, data.json
- Forget to commit .poly/ to git (contains index)

### Performance

 **DO**:
- Index once, query many times
- Batch operations when possible
- Use local operations (file read/write) for speed
- Save search results to avoid re-querying

 **DON'T**:
- Re-index on every query
- Make many small API calls (use limits)
- Query API when local search works

---

## Troubleshooting

### "No tools available"

**Cause**: IDE hasn't loaded Polyhedra MCP server

**Fix**:
1. Check MCP config file location and syntax
2. Restart IDE completely
3. Verify installation: pip show polyhedra
4. Check IDE console for error messages

---

### "Papers not indexed. Run index_papers first"

**Cause**: Trying to query before indexing

**Fix**:
`
"Index the papers in literature/my-papers.json first"
`

Then query again.

---

### "Papers file not found"

**Cause**: File path doesn't exist or incorrect

**Fix**:
1. Check file exists: "Get project status"
2. Use relative path from project root
3. Verify spelling: literature/papers.json not literature/paper.json

---

### "Invalid BibTeX format"

**Cause**: Malformed BibTeX entry

**Fix**:
- Ensure @article{key, format
- Include required fields: 	itle, uthor, year
- Close all braces: }
- Check for special characters in values

**Example valid entry**:
`ibtex
@article{smith2023,
  title={My Paper Title},
  author={Smith, John and Doe, Jane},
  year={2023},
  journal={Conference Name}
}
`

---

### "Rate limit exceeded"

**Cause**: Too many API requests to Semantic Scholar

**Fix**:
- Wait 60 seconds before next request
- Reduce search limits
- Use indexed/cached papers when possible
- Polyhedra automatically retries with exponential backoff

---

### Search returns no results

**Possible causes**:
1. **Query too specific**: Try broader terms
2. **Year filter too narrow**: Remove or expand year range
3. **Spelling error**: Check technical term spelling
4. **API issue**: Try again in a few minutes

**Fix**: Start broad, then narrow down

---

### Slow performance

**Indexing takes long**:
- Normal for large collections (>100 papers)
- First run downloads ML model (~50MB)
- Subsequent runs are faster

**Searches take long**:
- Normal for first API call (cold start)
- API rate limiting may cause delays
- Use indexed papers for faster local search

---

## Advanced Usage

### Batch Operations

**Add multiple citations**:
`
"Search for papers on [topic], then add all of them to my bibliography"
`

**Read multiple files**:
`
"Read all markdown files in the writing/ directory"
`

### Complex Queries

**Semantic Scholar supports**:
- Boolean operators: "attention AND transformers"
- Author filtering: "author:Vaswani"
- Venue filtering: "venue:NeurIPS"

**Example**:
`
"Search for 'author:Vaswani transformers' from 2017-2020"
`

### Chaining Workflows

**Automated pipeline**:
`
"Search for [topic], save to literature/, index them, 
 query for [specific aspect], add top 5 to citations,
 and give me a project status"
`

---

## Need More Help?

- **Documentation**: docs/API.md - Full API reference
- **Setup Guide**: docs/SETUP.md - Detailed IDE setup
- **Workflows**: docs/WORKFLOWS.md - More examples
- **Architecture**: docs/ARCHITECTURE.md - Technical details
- **Error Handling**: docs/ERROR_HANDLING.md - All error scenarios

---

## Quick Reference Card

| Task | Example Prompt |
|------|---------------|
| **Initialize** | "Initialize project 'my-research'" |
| **Search** | "Search for 'topic' papers from 2020-2023" |
| **Save Results** | "Save those papers to literature/papers.json" |
| **Add Citation** | "Add citation for the first paper" |
| **Index Papers** | "Index literature/papers.json" |
| **Find Similar** | "Find papers similar to 'concept'" |
| **Check Status** | "Get project status" |
| **Read File** | "Read writing/draft.md" |
| **Save File** | "Save [content] to writing/notes.md" |
| **List Citations** | "Show all my citations" |

---

**Happy Researching with Polyhedra! **