gr8monk3ys commited on
Commit
975967e
·
verified ·
1 Parent(s): c4b3657

Sync card and scripts from the monorepo

Browse files
Files changed (3) hide show
  1. app.py +43 -141
  2. core.py +188 -0
  3. hf_client.py +5 -0
app.py CHANGED
@@ -1,162 +1,64 @@
1
- """
2
- Code Explainer - AI-powered code explanation using HuggingFace Inference API.
3
- """
4
 
5
- import html
 
 
6
 
7
  import gradio as gr
8
- from pygments import highlight
9
- from pygments.lexers import get_lexer_by_name, guess_lexer
10
- from pygments.formatters import HtmlFormatter
11
 
 
 
 
 
 
 
 
 
 
 
12
  from hf_client import InferenceError, make_client, with_retry
13
 
14
- # ---------------------------------------------------------------------------
15
- # Configuration
16
- # ---------------------------------------------------------------------------
17
-
18
- MODEL_ID = "mistralai/Mistral-7B-Instruct-v0.3"
19
-
20
- LANGUAGES = [
21
- "Auto-detect",
22
- "Python",
23
- "JavaScript",
24
- "TypeScript",
25
- "Java",
26
- "C++",
27
- "C",
28
- "Go",
29
- "Rust",
30
- "Ruby",
31
- "PHP",
32
- "Swift",
33
- "Kotlin",
34
- "SQL",
35
- "Bash",
36
- "HTML/CSS",
37
- ]
38
-
39
- EXPLANATION_LEVELS = {
40
- "Beginner": "Explain this code in simple terms that a programming beginner would understand. Use analogies and avoid jargon. Focus on the 'what' rather than technical details.",
41
- "Intermediate": "Explain this code for someone with basic programming knowledge. Include technical details but explain any advanced concepts. Discuss both what the code does and how it works.",
42
- "Advanced": "Provide a thorough technical analysis of this code. Discuss implementation details, time/space complexity, potential edge cases, and possible improvements or alternatives.",
43
- }
44
-
45
- # ---------------------------------------------------------------------------
46
- # Initialize client
47
- # ---------------------------------------------------------------------------
48
-
49
  client = make_client(MODEL_ID)
50
 
51
- # ---------------------------------------------------------------------------
52
- # Utility functions
53
- # ---------------------------------------------------------------------------
54
-
55
-
56
- def detect_language(code: str) -> str:
57
- """Attempt to detect the programming language."""
58
- try:
59
- lexer = guess_lexer(code)
60
- return lexer.name
61
- except Exception:
62
- return "Unknown"
63
-
64
-
65
- def format_code_html(code: str, language: str) -> str:
66
- """Apply syntax highlighting to code."""
67
- try:
68
- if language == "Auto-detect" or language == "Unknown":
69
- lexer = guess_lexer(code)
70
- else:
71
- lang_map = {
72
- "JavaScript": "javascript",
73
- "TypeScript": "typescript",
74
- "C++": "cpp",
75
- "HTML/CSS": "html",
76
- "Bash": "bash",
77
- }
78
- lang_key = lang_map.get(language, language.lower())
79
- lexer = get_lexer_by_name(lang_key)
80
-
81
- formatter = HtmlFormatter(style="monokai", noclasses=True)
82
- return highlight(code, lexer, formatter)
83
- except Exception:
84
- return f"<pre><code>{html.escape(code)}</code></pre>"
85
-
86
-
87
- # ---------------------------------------------------------------------------
88
- # Main explanation function
89
- # ---------------------------------------------------------------------------
90
 
91
-
92
- def explain_code(code: str, language: str, level: str) -> tuple[str, str]:
93
- """Generate an explanation for the provided code."""
94
- if not code.strip():
95
- return "Please paste some code to explain.", ""
96
-
97
- # Detect language if auto
98
- detected_lang = language
99
- if language == "Auto-detect":
100
- detected_lang = detect_language(code)
101
-
102
- # Build prompt
103
- level_instruction = EXPLANATION_LEVELS.get(
104
- level, EXPLANATION_LEVELS["Intermediate"]
105
  )
106
- lexer_hint = detected_lang.split()[0].lower() if detected_lang.strip() else ""
107
-
108
- system_prompt = f"You are an expert programming tutor. {level_instruction}"
109
- user_prompt = f"""Explain the following code.
110
 
111
- ```{lexer_hint}
112
- {code}
113
- ```
114
 
115
- Provide a structured explanation with the following sections:
116
-
117
- ## Overview
118
- A brief summary of what this code does (2-3 sentences).
119
-
120
- ## Step-by-Step Breakdown
121
- Explain the code section by section, describing what each part does.
122
-
123
- ## Key Concepts
124
- List and briefly explain the important programming concepts used in this code.
125
 
126
- ## Potential Improvements
127
- Suggest any improvements, best practices, or potential issues to be aware of.
128
 
129
- Keep your explanation clear, accurate, and educational."""
 
130
 
 
 
 
131
  try:
132
- completion = with_retry(
133
- client.chat_completion,
134
- messages=[
135
- {"role": "system", "content": system_prompt},
136
- {"role": "user", "content": user_prompt},
137
- ],
138
- max_tokens=1500,
139
- temperature=0.7,
140
- top_p=0.95,
141
- )
142
- explanation = completion.choices[0].message.content.strip()
143
 
144
- # Add language badge
145
- explanation = (
146
- f"**Detected Language:** `{detected_lang}`\n\n---\n\n{explanation}"
147
- )
148
 
149
- # Format the code with syntax highlighting
150
- formatted_code = format_code_html(code, detected_lang)
151
 
152
- return explanation, formatted_code
153
-
154
- except InferenceError as e:
155
- return f"**{e}**", format_code_html(code, detected_lang)
156
-
157
-
158
- # ---------------------------------------------------------------------------
159
- # Gradio Interface
160
  # ---------------------------------------------------------------------------
161
 
162
  EXAMPLE_CODE = '''def fibonacci(n):
@@ -216,7 +118,7 @@ with gr.Blocks(title="Code Explainer", theme=gr.themes.Soft()) as demo:
216
  explanation_output = gr.Markdown(label="Explanation")
217
 
218
  explain_btn.click(
219
- fn=explain_code,
220
  inputs=[code_input, language_dropdown, level_dropdown],
221
  outputs=[explanation_output, formatted_code_output],
222
  )
 
1
+ """Code Explainer -- a Gradio front end over :mod:`core`.
 
 
2
 
3
+ Owns the UI and the adapters: builds the Inference client, wraps it as the
4
+ ``chat_fn`` core expects, and renders the returned Explanation.
5
+ """
6
 
7
  import gradio as gr
 
 
 
8
 
9
+ from core import (
10
+ AUTO_DETECT,
11
+ EXPLANATION_LEVELS,
12
+ LANGUAGES,
13
+ Explanation,
14
+ InputError,
15
+ detect_language,
16
+ explain_code,
17
+ highlight_code,
18
+ )
19
  from hf_client import InferenceError, make_client, with_retry
20
 
21
+ MODEL_ID = "mistralai/Mistral-7B-Instruct-v0.2"
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
22
  client = make_client(MODEL_ID)
23
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
24
 
25
+ def _chat(messages, *, max_tokens, temperature, top_p) -> str:
26
+ """Call the Inference API, retrying transient failures."""
27
+ completion = with_retry(
28
+ client.chat_completion,
29
+ messages=messages,
30
+ max_tokens=max_tokens,
31
+ temperature=temperature,
32
+ top_p=top_p,
 
 
 
 
 
 
33
  )
34
+ return completion.choices[0].message.content
 
 
 
35
 
 
 
 
36
 
37
+ def _render(explanation: Explanation) -> str:
38
+ """Format an Explanation as the Markdown shown in the output pane."""
39
+ return (
40
+ f"**Detected Language:** `{explanation.detected_language}`"
41
+ f"\n\n---\n\n{explanation.body}"
42
+ )
 
 
 
 
43
 
 
 
44
 
45
+ def handle_explain(code: str, language: str, level: str) -> tuple[str, str]:
46
+ """Gradio handler: explain the code, or report why not.
47
 
48
+ The code pane is filled in either way -- a failed explanation should not
49
+ also cost the user the highlighted view of what they pasted.
50
+ """
51
  try:
52
+ explanation = explain_code(code, language, level, chat_fn=_chat)
53
+ except InputError as exc:
54
+ return str(exc), ""
55
+ except InferenceError as exc:
56
+ resolved = detect_language(code) if language == AUTO_DETECT else language
57
+ return f"**{exc}**", highlight_code(code, resolved)
 
 
 
 
 
58
 
59
+ return _render(explanation), explanation.highlighted_code
 
 
 
60
 
 
 
61
 
 
 
 
 
 
 
 
 
62
  # ---------------------------------------------------------------------------
63
 
64
  EXAMPLE_CODE = '''def fibonacci(n):
 
118
  explanation_output = gr.Markdown(label="Explanation")
119
 
120
  explain_btn.click(
121
+ fn=handle_explain,
122
  inputs=[code_input, language_dropdown, level_dropdown],
123
  outputs=[explanation_output, formatted_code_output],
124
  )
core.py ADDED
@@ -0,0 +1,188 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Code explanation logic, independent of Gradio and of the Inference API.
2
+
3
+ The entry point is :func:`explain_code`, which owns the sequence: validate,
4
+ resolve the language, build the prompt, call the model, and return an
5
+ :class:`Explanation`. Rendering is ``app.py``'s job -- see
6
+ docs/adr/0002-coarse-entry-point-for-space-core-modules.md.
7
+
8
+ :func:`detect_language` and :func:`highlight_code` are public because the UI
9
+ needs them on their own: when explanation fails, the code pane is still shown
10
+ highlighted.
11
+ """
12
+
13
+ from dataclasses import dataclass
14
+ from typing import Protocol
15
+
16
+ # ---------------------------------------------------------------------------
17
+ # Configuration
18
+ # ---------------------------------------------------------------------------
19
+ LANGUAGES = [
20
+ "Auto-detect",
21
+ "Python",
22
+ "JavaScript",
23
+ "TypeScript",
24
+ "Java",
25
+ "C++",
26
+ "C",
27
+ "Go",
28
+ "Rust",
29
+ "Ruby",
30
+ "PHP",
31
+ "Swift",
32
+ "Kotlin",
33
+ "SQL",
34
+ "Bash",
35
+ "HTML/CSS",
36
+ ]
37
+
38
+ EXPLANATION_LEVELS = {
39
+ "Beginner": "Explain this code in simple terms that a programming beginner would understand. Use analogies and avoid jargon. Focus on the 'what' rather than technical details.",
40
+ "Intermediate": "Explain this code for someone with basic programming knowledge. Include technical details but explain any advanced concepts. Discuss both what the code does and how it works.",
41
+ "Advanced": "Provide a thorough technical analysis of this code. Discuss implementation details, time/space complexity, potential edge cases, and possible improvements or alternatives.",
42
+ }
43
+
44
+
45
+ # Pygments' name for a language, where it differs from the label we show.
46
+ _LEXER_NAMES = {
47
+ "JavaScript": "javascript",
48
+ "TypeScript": "typescript",
49
+ "C++": "cpp",
50
+ "HTML/CSS": "html",
51
+ "Bash": "bash",
52
+ }
53
+
54
+ AUTO_DETECT = "Auto-detect"
55
+ UNKNOWN = "Unknown"
56
+
57
+ MAX_TOKENS = 1500
58
+ TOP_P = 0.95
59
+ TEMPERATURE = 0.7
60
+
61
+
62
+ class InputError(ValueError):
63
+ """The caller supplied no code to explain."""
64
+
65
+
66
+ class ChatFn(Protocol):
67
+ """Send *messages* to a chat model and return its reply.
68
+
69
+ Implementations may raise; :func:`explain_code` lets those propagate rather
70
+ than substituting a plausible-looking explanation.
71
+ """
72
+
73
+ def __call__(
74
+ self,
75
+ messages: list[dict],
76
+ *,
77
+ max_tokens: int,
78
+ temperature: float,
79
+ top_p: float,
80
+ ) -> str: ...
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class Explanation:
85
+ """The result of explaining one snippet of code."""
86
+
87
+ detected_language: str
88
+ body: str
89
+ highlighted_code: str
90
+
91
+
92
+ def detect_language(code: str) -> str:
93
+ """Guess the language of *code*, or return ``"Unknown"``."""
94
+ from pygments.lexers import guess_lexer
95
+
96
+ try:
97
+ return guess_lexer(code).name
98
+ except Exception: # noqa: BLE001 - pygments raises freely; Unknown is the fallback
99
+ return UNKNOWN
100
+
101
+
102
+ def highlight_code(code: str, language: str) -> str:
103
+ """Return *code* as syntax-highlighted HTML.
104
+
105
+ Falls back to escaped plain text: highlighting is decoration, and failing to
106
+ decorate must not cost the user sight of their own code.
107
+ """
108
+ import html
109
+
110
+ from pygments import highlight
111
+ from pygments.formatters import HtmlFormatter
112
+ from pygments.lexers import get_lexer_by_name, guess_lexer
113
+
114
+ try:
115
+ if language in (AUTO_DETECT, UNKNOWN):
116
+ lexer = guess_lexer(code)
117
+ else:
118
+ lexer = get_lexer_by_name(_LEXER_NAMES.get(language, language.lower()))
119
+ return highlight(code, lexer, HtmlFormatter(style="monokai", noclasses=True))
120
+ except Exception: # noqa: BLE001 - decoration only; show the code regardless
121
+ return f"<pre><code>{html.escape(code)}</code></pre>"
122
+
123
+
124
+ def _build_user_prompt(code: str, language: str) -> str:
125
+ lexer_hint = language.split()[0].lower() if language.strip() else ""
126
+ return f"""Explain the following code.
127
+
128
+ ```{lexer_hint}
129
+ {code}
130
+ ```
131
+
132
+ Provide a structured explanation with the following sections:
133
+
134
+ ## Overview
135
+ A brief summary of what this code does (2-3 sentences).
136
+
137
+ ## Step-by-Step Breakdown
138
+ Explain the code section by section, describing what each part does.
139
+
140
+ ## Key Concepts
141
+ List and briefly explain the important programming concepts used in this code.
142
+
143
+ ## Potential Improvements
144
+ Suggest any improvements, best practices, or potential issues to be aware of.
145
+
146
+ Keep your explanation clear, accurate, and educational."""
147
+
148
+
149
+ def explain_code(
150
+ code: str,
151
+ language: str,
152
+ level: str,
153
+ *,
154
+ chat_fn: ChatFn,
155
+ ) -> Explanation:
156
+ """Explain *code* at the requested *level*.
157
+
158
+ An unrecognised *level* falls back to Intermediate rather than failing: the
159
+ value comes from a dropdown, so a bad one means a UI change, not bad input.
160
+
161
+ Raises:
162
+ InputError: *code* is empty or whitespace.
163
+ Exception: whatever *chat_fn* raises.
164
+ """
165
+ if not code.strip():
166
+ raise InputError("Please paste some code to explain.")
167
+
168
+ resolved = detect_language(code) if language == AUTO_DETECT else language
169
+ instruction = EXPLANATION_LEVELS.get(level, EXPLANATION_LEVELS["Intermediate"])
170
+
171
+ body = chat_fn(
172
+ [
173
+ {
174
+ "role": "system",
175
+ "content": f"You are an expert programming tutor. {instruction}",
176
+ },
177
+ {"role": "user", "content": _build_user_prompt(code, resolved)},
178
+ ],
179
+ max_tokens=MAX_TOKENS,
180
+ temperature=TEMPERATURE,
181
+ top_p=TOP_P,
182
+ )
183
+
184
+ return Explanation(
185
+ detected_language=resolved,
186
+ body=body.strip(),
187
+ highlighted_code=highlight_code(code, resolved),
188
+ )
hf_client.py CHANGED
@@ -1,5 +1,10 @@
1
  """Helpers for talking to the HuggingFace Inference API.
2
 
 
 
 
 
 
3
  Centralises the three things every Space here needs and previously got wrong:
4
 
5
  * **Authentication** -- reads ``HF_TOKEN`` from the environment. The serverless
 
1
  """Helpers for talking to the HuggingFace Inference API.
2
 
3
+ VENDORED MODULE -- a byte-identical copy lives in each Space folder that needs
4
+ it, because a Space is uploaded as a flat directory and cannot import from
5
+ outside itself. Edit every copy in the same commit; tests/test_vendored.py
6
+ fails otherwise. See docs/adr/0001-vendoring-is-the-only-sharing-mechanism.md.
7
+
8
  Centralises the three things every Space here needs and previously got wrong:
9
 
10
  * **Authentication** -- reads ``HF_TOKEN`` from the environment. The serverless