File size: 8,736 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
# IDE Setup Guide

This guide will help you configure Polyhedra in your IDE in less than 5 minutes.

## Prerequisites

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

## Installation

### Step 1: Install Polyhedra

Using pip:
```bash
pip install polyhedra
```

Using uv (recommended):
```bash
uv pip install polyhedra
```

### Step 2: Verify Installation

```bash
polyhedra --version
```

## IDE Configuration

Choose your IDE and follow the specific setup instructions:

### Cursor Setup

1. **Create MCP config directory** (if it doesn't exist):
   ```bash
   mkdir -p ~/.cursor
   ```

2. **Create or edit `~/.cursor/mcp.json`**:
   ```json
   {
     "mcpServers": {
       "polyhedra": {
         "command": "uvx",
         "args": ["--from", "polyhedra", "polyhedra"],
         "env": {}
       }
     }
   }
   ```

3. **Add `.cursorrules` to your project** (optional but recommended):
   Copy `.cursorrules` from the Polyhedra repository to your research project root.

4. **Restart Cursor**

5. **Verify**: Open Cursor chat and type "List available Polyhedra tools"

### VS Code + GitHub Copilot Setup

1. **Install GitHub Copilot Chat extension** (if not already installed)

2. **Add to your workspace `.vscode/settings.json`**:
   ```json
   {
     "github.copilot.chat.codeGeneration.instructions": [
       {
         "text": "When working on research projects, use the Polyhedra MCP tools to search papers, manage citations, and organize literature."
       }
     ],
     "mcp.servers": {
       "polyhedra": {
         "command": "uvx",
         "args": ["--from", "polyhedra", "polyhedra"],
         "env": {}
       }
     }
   }
   ```

3. **Add `.github/copilot-instructions.md`** to your project (optional):
   Copy `copilot-instructions.md` from the Polyhedra repository.

4. **Restart VS Code**

5. **Verify**: Open Copilot Chat and ask "What Polyhedra tools are available?"

### Windsurf Setup

1. **Create MCP config directory** (if it doesn't exist):
   ```bash
   mkdir -p ~/.windsurf
   ```

2. **Create or edit `~/.windsurf/mcp.json`**:
   ```json
   {
     "mcpServers": {
       "polyhedra": {
         "command": "uvx",
         "args": ["--from", "polyhedra", "polyhedra"],
         "env": {}
       }
     }
   }
   ```

3. **Add `.cursorrules` to your project** (Windsurf uses same format):
   Copy `.cursorrules` from the Polyhedra repository to your research project root.

4. **Restart Windsurf**

5. **Verify**: Open chat and ask about available tools

### VS Code + MCP Extension Setup

1. **Install the MCP extension** from VS Code marketplace

2. **Add to your workspace `.vscode/settings.json`**:
   ```json
   {
     "mcp.servers": {
       "polyhedra": {
         "command": "uvx",
         "args": ["--from", "polyhedra", "polyhedra"],
         "env": {}
       }
     }
   }
   ```

3. **Restart VS Code**

4. **Verify**: Check the MCP extension panel for Polyhedra tools

## Initialize Your First Project

Once configured, initialize a new research project:

1. **Create project directory**:
   ```bash
   mkdir my-research-project
   cd my-research-project
   ```

2. **In your IDE chat, run**:
   ```
   Use init_project to set up this research project
   ```

3. **Verify the structure was created**:
   ```
   literature/
   ideas/
   method/
   paper/
   references.bib
   .poly/
   ```

## Quick Start Example

Try this workflow in your IDE chat:

1. **Search for papers**:
   ```
   Search for recent papers on "large language models" from 2023-2024
   ```

2. **Add a citation**:
   ```
   Add this paper to my bibliography: [paste BibTeX]
   ```

3. **Get project status**:
   ```
   Show me my current project status
   ```

## LLM Configuration (for v2.1 Literature Review Features)

Polyhedra v2.1 adds AI-powered literature review generation. This requires an API key from Anthropic or OpenAI.

### Option 1: Anthropic Claude (Recommended)

**Why Claude?** Better academic writing, lower cost ($3/M input, $15/M output)

1. **Get API Key**:
   - Visit https://console.anthropic.com/
   - Sign up or log in
   - Navigate to **API Keys** section
   - Click **Create Key** (name it "Polyhedra")
   - Copy the key (starts with `sk-ant-`)

2. **Configure Environment Variable**:
   
   **Windows**:
   ```powershell
   $env:ANTHROPIC_API_KEY = "sk-ant-api03-your-key-here"
   # Or add permanently:
   setx ANTHROPIC_API_KEY "sk-ant-api03-your-key-here"
   ```
   
   **Mac/Linux**:
   ```bash
   export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
   # Add to ~/.bashrc or ~/.zshrc for persistence
   ```
   
   **Or create `.env` file** in your project:
   ```bash
   ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
   ```

3. **Verify Configuration**:
   ```
   # In your IDE chat:
   "Estimate cost for reviewing 50 papers"
   ```
   Should return cost estimate without errors.

### Option 2: OpenAI GPT

**Why GPT?** You may already have an account, familiar models

1. **Get API Key**:
   - Visit https://platform.openai.com/api-keys
   - Sign up or log in
   - Click **Create new secret key**
   - Copy the key (starts with `sk-`)

2. **Configure**:
   ```bash
   export OPENAI_API_KEY=sk-your-key-here
   export POLYHEDRA_LLM_PROVIDER=openai  # Optional: specify provider
   ```

3. **Model Selection** (optional):
   ```bash
   export POLYHEDRA_LLM_MODEL=gpt-4-turbo  # Default: gpt-4o
   ```

### Cost Management

**Set maximum cost per operation** (recommended):
```bash
export POLYHEDRA_MAX_COST=1.00  # Default: $1.00
```

Polyhedra will:
- βœ… Estimate cost before each review generation
- βœ… Warn if estimated cost exceeds $0.10
- βœ… Block operations exceeding `POLYHEDRA_MAX_COST` (unless forced)
- βœ… Log all LLM API calls with token counts

**Example `.env` file**:
```bash
# LLM Provider (choose one)
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
# OPENAI_API_KEY=sk-your-key-here

# Optional: Provider selection (default: anthropic)
# POLYHEDRA_LLM_PROVIDER=anthropic

# Optional: Cost limit (default: $1.00)
POLYHEDRA_MAX_COST=0.50

# Optional: Model override
# POLYHEDRA_LLM_MODEL=claude-3-5-sonnet-20241022
```

### Verify LLM Setup

In your IDE chat:
```
"Check if my LLM configuration is working"
```

Should confirm:
- βœ“ API key detected
- βœ“ Provider configured (anthropic or openai)
- βœ“ Connection successful
- βœ“ Ready to generate reviews

### LLM Features

Once configured, you can:

1. **Generate Literature Reviews**:
   ```
   "Generate a literature review from my papers focused on efficiency"
   ```

2. **Estimate Costs**:
   ```
   "Estimate cost for reviewing 75 papers with comprehensive depth"
   ```

3. **Check Budget**:
   ```
   "What's my current cost limit?"
   ```

**Note**: All v2.0 features (search, citations, files) work WITHOUT LLM configuration. Only literature review generation requires API keys.

---

## Troubleshooting

### "Command not found: uvx"

Install `uv`:
```bash
pip install uv
```

Or use `python -m polyhedra` instead:
```json
{
  "command": "python",
  "args": ["-m", "polyhedra"]
}
```

### "No tools available"

1. Check that Polyhedra is installed: `pip list | grep polyhedra`
2. Verify the MCP config file is in the correct location
3. Restart your IDE completely
4. Check IDE logs for MCP connection errors

### "Tool execution failed"

1. Verify you're in a project directory
2. Check that required files exist (e.g., `literature/papers.json` for indexing)
3. Ensure you have internet connectivity for paper searches

### "LLM service not configured"

This error appears when trying to use literature review generation without API keys:

1. Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` environment variable
2. Restart your IDE to pick up the new environment variable
3. Verify with: `"Check if my LLM configuration is working"`

### "API rate limit exceeded"

**Anthropic**: 50 requests/minute limit
- Wait 60 seconds and retry
- Check your API usage dashboard

**OpenAI**: Varies by account tier
- Upgrade your account tier
- Wait for rate limit reset

### "Cost exceeds configured limit"

If you see: `"Estimated cost $0.75 exceeds limit $0.50"`

**Options**:
1. Increase limit: `export POLYHEDRA_MAX_COST=1.00`
2. Reduce paper count or use brief depth
3. Force execution: Add `force=true` to your request (not recommended)

## Next Steps

- Read the [API Documentation](API.md) for detailed tool information
- Follow [Example Workflows](WORKFLOWS.md) for common research tasks
- Check the [Architecture Guide](ARCHITECTURE.md) to understand how Polyhedra works

## Getting Help

- GitHub Issues: https://github.com/polyhedra/polyhedra/issues
- Documentation: https://github.com/polyhedra/polyhedra#readme