Initial commit for HF Spaces

.dockerignore

@@ -0,0 +1,10 @@
+IELTS-Assistant/
+pycache/
+*.pyc
+.env
+logs/
+*.spec
+build/
+dist/
+tmp/
+.gitignore

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,9 @@
+IELTS-Assistant/
+pycache/
+*.pyc
+.env
+logs/
+*.spec
+build/
+dist/
+tmp/

README.md

@@ -1,13 +1,11 @@
 ---
 title: IELTS Writing Assistant
-emoji: 🦀
-colorFrom: blue
+emoji: ✍️
+colorFrom: indigo
 colorTo: pink
 sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
+sdk_version: 4.44.0
+app_file: app/ui.py   # <— point to your file
 pinned: false
 license: mit
 ---
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

adapters/env.py

@@ -0,0 +1,17 @@
+import os
+from contextlib import contextmanager
+
+@contextmanager
+def temp_env(var: str, value: str | None):
+    old = os.environ.get(var)
+    try:
+        if value is None:
+            os.environ.pop(var, None)
+        else:
+            os.environ[var] = value
+        yield
+    finally:
+        if old is None:
+            os.environ.pop(var, None)
+        else:
+            os.environ[var] = old

adapters/external/part1_runner.py

@@ -0,0 +1,24 @@
+from typing import Optional
+from pathlib import Path
+import logging
+from inspect import signature
+from vendors.part1.main import run_ielts_part1_agent
+from utils.env import temp_env
+
+logger = logging.getLogger(__name__)
+
+def run_part1(image_path: str | Path, essay_text: str, api_key: Optional[str] = None) -> str:
+    image_path = Path(image_path)
+    if not image_path.exists():
+        raise FileNotFoundError(f"Image not found: {image_path}")
+
+    logger.info("Running Part1 agent")
+
+    try:
+        if "api_key" in signature(run_ielts_part1_agent).parameters and api_key:
+            return str(run_ielts_part1_agent(str(image_path), essay_text, api_key=api_key))
+    except Exception:
+        pass
+
+    with temp_env("GOOGLE_API_KEY", api_key):
+        return str(run_ielts_part1_agent(str(image_path), essay_text))

adapters/external/part2_runner.py

@@ -0,0 +1,17 @@
+import logging
+from inspect import signature
+from typing import Optional
+from vendors.part2.main import run_ielts_part2_agent
+from utils.env import temp_env
+
+logger = logging.getLogger(__name__)
+
+def run_part2(question: str, essay_text: str, api_key: Optional[str] = None) -> str:
+    logger.info("Running Part2 agent")
+    try:
+        if "api_key" in signature(run_ielts_part2_agent).parameters and api_key:
+            return str(run_ielts_part2_agent(question, essay_text, api_key=api_key))
+    except Exception:
+        pass
+    with temp_env("GOOGLE_API_KEY", api_key):
+        return str(run_ielts_part2_agent(question, essay_text))

app/app.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+import gradio as gr
+from core.config import get_api_key, set_api_key, ENV_VAR_NAME, in_hf_spaces
+from core.pipeline import analyze_part1, analyze_part2
+from core.logging_config import configure_logging
+import logging
+
+configure_logging()
+logger = logging.getLogger(__name__)
+
+session_key = gr.State("")
+
+def _effective_key(user_input_key: str | None) -> str | None:
+    """Priority: user input (session) > env (local or Space Secret)."""
+    k = (user_input_key or "").strip()
+    if k:
+        return k
+    return get_api_key()
+
+def on_save_key_local(key: str):
+    if in_hf_spaces():
+        return gr.update(value="**On Spaces, keys are not stored. Use the key box per session or set a Space Secret.**")
+    set_api_key(key)
+    return gr.update(value="**Saved!** Your API key is now in .env.")
+
+def on_store_key_session(key: str):
+    session_key.value = (key or "").strip()
+    return gr.update(value="**Saved for this session.**")
+
+def on_analyze_part1(image_path, essay, key_box):
+    key = _effective_key(key_box or session_key.value)
+    if not key:
+        raise RuntimeError(f"Provide {ENV_VAR_NAME} in Settings.")
+    if not image_path:
+        raise ValueError("Please upload the Task 1 image/chart/graph.")
+    if not essay or len(essay.strip()) < 30:
+        raise ValueError("Please paste your full Task 1 response (≥30 chars).")
+    logger.info("UI: analyze_part1 invoked")
+    return analyze_part1(image_path, essay, api_key=key)
+
+def on_analyze_part2(question, essay, key_box):
+    key = _effective_key(key_box or session_key.value)
+    if not key:
+        raise RuntimeError(f"Provide {ENV_VAR_NAME} in Settings.")
+    if not question or len(question.strip()) < 10:
+        raise ValueError("Please paste the Task 2 question.")
+    if not essay or len(essay.strip()) < 30:
+        raise ValueError("Please paste your full Task 2 essay (≥30 chars).")
+    logger.info("UI: analyze_part2 invoked")
+    return analyze_part2(question, essay, api_key=key)
+
+with gr.Blocks(title="IELTS Writing Assistant", fill_height=True) as demo:
+    gr.Markdown("# IELTS Writing Assistant\nLocal-first app using your existing agents.")
+
+    with gr.Tab("Task 1"):
+        with gr.Row():
+            image = gr.Image(type="filepath", label="Task 1 Image/Chart/Graph")
+            essay1 = gr.Textbox(label="Your Task 1 Essay", lines=18)
+        with gr.Row():
+            btn1 = gr.Button("Analyze", variant="primary")
+            clear1 = gr.Button("Clear")
+        out1 = gr.Markdown(label="Feedback")
+
+    with gr.Tab("Task 2"):
+        question = gr.Textbox(label="Task 2 Question", lines=4)
+        essay2 = gr.Textbox(label="Your Task 2 Essay", lines=18)
+        with gr.Row():
+            btn2 = gr.Button("Analyze", variant="primary")
+            clear2 = gr.Button("Clear")
+        out2 = gr.Markdown(label="Feedback")
+
+    with gr.Tab("Settings"):
+        gr.Markdown(
+            f"Set your API key. Locally, you can save to `.env`. On Spaces, use **Session Key** or set a **Space Secret** `{ENV_VAR_NAME}`."
+        )
+        key_box = gr.Textbox(label=f"{ENV_VAR_NAME}", type="password", placeholder="sk-...")
+        save_local = gr.Button("Save to .env (Local Only)")
+        save_session = gr.Button("Save Session Key")
+        status = gr.Markdown("")
+
+    btn1.click(on_analyze_part1, inputs=[image, essay1, key_box], outputs=[out1])
+    clear1.click(lambda: (None, "", ""), outputs=[image, essay1, out1])
+
+    btn2.click(on_analyze_part2, inputs=[question, essay2, key_box], outputs=[out2])
+    clear2.click(lambda: ("", ""), outputs=[question, out2])
+
+    save_local.click(on_save_key_local, inputs=[key_box], outputs=[status])
+    save_session.click(on_store_key_session, inputs=[key_box], outputs=[status])
+
+if __name__ == "__main__":
+    demo.queue().launch()

core/config.py

@@ -0,0 +1,36 @@
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+ENV_PATH = Path(".env")
+ENV_VAR_NAME = "GOOGLE_API_KEY"
+
+load_dotenv(dotenv_path=ENV_PATH, override=False)
+
+def in_hf_spaces() -> bool:
+    return bool(os.getenv("SPACE_ID"))
+
+def get_api_key() -> str | None:
+    return os.getenv(ENV_VAR_NAME)
+
+def ensure_env_file() -> None:
+    if not ENV_PATH.exists():
+        ENV_PATH.write_text("")
+
+def set_api_key(value: str, var_name: str = ENV_VAR_NAME) -> None:
+    if in_hf_spaces():
+        return  
+    value = (value or "").strip()
+    ensure_env_file()
+    lines = ENV_PATH.read_text().splitlines()
+    out, found = [], False
+    for line in lines:
+        if line.strip().startswith(f"{var_name}="):
+            out.append(f"{var_name}={value}")
+            found = True
+        else:
+            out.append(line)
+    if not found:
+        out.append(f"{var_name}={value}")
+    ENV_PATH.write_text("\n".join(out) + "\n")
+    os.environ[var_name] = value  

core/formatting.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+import re
+
+_ANSI_RE = re.compile(r"\x1B\[[0-?]*[ -/]*[@-~]")
+
+def _strip_ansi(s: str) -> str:
+    return _ANSI_RE.sub("", s)
+
+def _normalize_agent_text_to_md(s: str) -> str:
+    s = _strip_ansi(s)
+
+    s = re.sub(r"(?im)\s*-{3,}\s*([^-\n][^\n]{0,80}?)\s*-{3,}\s*", r"\n## \1\n\n", s)
+    s = re.sub(r"(?m)^(\d+\.\s+[^:\n]+:)", r"**\1**", s)
+    s = re.sub(r"\n{3,}", "\n\n", s)
+
+    return s.strip()
+
+def format_success(title: str, body_md_or_text: str) -> str:
+    body = _normalize_agent_text_to_md(body_md_or_text)
+    return f"# {title}\n\n{body}"
+
+def format_error(err: Exception | str) -> str:
+    msg = str(err)
+    return (
+        "## ❌ Error\n\n"
+        f"{msg}\n\n"
+        "> Tip: Check your API key in Settings, and verify your inputs."
+    )

core/logging_config.py

@@ -0,0 +1,24 @@
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+LOG_PATH = Path("logs")
+LOG_PATH.mkdir(exist_ok=True)
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    logger = logging.getLogger()
+    logger.setLevel(level)
+
+    fmt = logging.Formatter(
+        fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    ch = logging.StreamHandler()
+    ch.setFormatter(fmt)
+    logger.addHandler(ch)
+
+    fh = RotatingFileHandler(LOG_PATH / "app.log", maxBytes=1_000_000, backupCount=3)
+    fh.setFormatter(fmt)
+    logger.addHandler(fh)

core/pipeline.py

@@ -0,0 +1,17 @@
+import logging
+from pathlib import Path
+from adapters.external.part1_runner import run_part1
+from adapters.external.part2_runner import run_part2
+from core.formatting import format_success
+
+logger = logging.getLogger(__name__)
+
+def analyze_part1(image_path: str | Path, essay_text: str, api_key: str | None = None) -> str:
+    logger.info("Pipeline: analyze_part1")
+    result_md = run_part1(image_path, essay_text, api_key=api_key)
+    return format_success("IELTS Writing Task 1 — Feedback", result_md)
+
+def analyze_part2(question: str, essay_text: str, api_key: str | None = None) -> str:
+    logger.info("Pipeline: analyze_part2")
+    result_md = run_part2(question, essay_text, api_key=api_key)
+    return format_success("IELTS Writing Task 2 — Feedback", result_md)

requirements.txt

@@ -0,0 +1,14 @@
+gradio==5.49.1
+gradio-client==1.13.3
+python-dotenv==1.0.1
+Pillow==10.4.0
+rich==13.7.1
+
+langchain-community==0.3.30
+langgraph==0.6.7
+ipython==8.37.0
+typing-extensions==4.15.0
+langchain-core==0.3.76
+pydantic==2.11.9
+requests==2.32.5
+langchain-google-genai==2.1.12

tests/test_smoke.py

@@ -0,0 +1,10 @@
+from core.config import set_api_key, get_api_key
+
+def test_env_setter(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    from importlib import reload
+    import core.config as cfg
+    reload(cfg)
+    assert cfg.get_api_key() is None
+    cfg.set_api_key("abc")
+    assert cfg.get_api_key() == "abc"

utils/files.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+import tempfile
+from contextlib import contextmanager
+
+@contextmanager
+def temp_copy(path: str | Path):
+    src = Path(path)
+    if not src.exists():
+        raise FileNotFoundError(src)
+    with tempfile.TemporaryDirectory() as td:
+        dst = Path(td) / src.name
+        dst.write_bytes(src.read_bytes())
+        yield dst

vendors/part1/Workflow.md

@@ -0,0 +1,28 @@
+```mermaid
+---
+config:
+  flowchart:
+    curve: linear
+---
+graph TD;
+	__start__([<p>__start__</p>]):::first
+	Task_Response(Task Response)
+	Lexical(Lexical)
+	Grammar(Grammar)
+	CC(CC)
+	Aggregator(Aggregator)
+	__end__([<p>__end__</p>]):::last
+	CC --> Aggregator;
+	Grammar --> Aggregator;
+	Lexical --> Aggregator;
+	Task_Response --> Aggregator;
+	__start__ --> CC;
+	__start__ --> Grammar;
+	__start__ --> Lexical;
+	__start__ --> Task_Response;
+	Aggregator --> __end__;
+	classDef default fill:#f2f0ff,line-height:1.2
+	classDef first fill-opacity:0
+	classDef last fill:#bfb6fc
+
+```

vendors/part1/display_report.py

@@ -0,0 +1,63 @@
+import json
+import re
+import textwrap
+
+
+class styles:
+    HEADER = '\033[95m'
+    GREEN = '\033[92m'
+    WARNING = '\033[93m'
+    BOLD = '\033[1m'
+    UNDERLINE = '\033[4m'
+    ENDC = '\033[0m'
+
+
+def print_md(text):
+    """
+    Translates simple markdown and wraps text for better terminal display.
+    """
+    text = re.sub(r'\*\*(.*?)\*\*', f'{styles.BOLD}\\1{styles.ENDC}', text)
+    paragraphs = text.split('\n')
+    wrapped_paragraphs = [textwrap.fill(p, width=90) for p in paragraphs]
+    final_text = '\n'.join(wrapped_paragraphs)
+    print(final_text)
+
+
+def display_report_fn(data):
+    """
+    Loads, parses, and prints the formatted IELTS report from a JSON file.
+    """
+
+    print("\n" + "=" * 80)
+    print(f"{styles.HEADER}{styles.BOLD}📝 IELTS WRITING EVALUATION REPORT{styles.ENDC}")
+    print("=" * 80)
+
+    if "original_question" in data:
+        print(f"\n{styles.HEADER}{styles.UNDERLINE}Original Question:{styles.ENDC}")
+        print_md(data["original_question"])
+
+    if "student_essay" in data:
+        print(f"\n{styles.HEADER}{styles.UNDERLINE}Student's Essay:{styles.ENDC}")
+        print_md(data["student_essay"])
+        print("-" * 80)
+
+    sections = {
+        "task_response": "✅ Task Response",
+        "coherence_and_cohesion": "🔗 Coherence and Cohesion",
+        "lexical_resource": "📚 Lexical Resource",
+        "grammatical_range_and_accuracy": "📝 Grammatical Range and Accuracy"
+    }
+
+    for key, title in sections.items():
+        if key in data:
+            print(f"\n\n{styles.GREEN}{styles.BOLD}{styles.UNDERLINE}--- {title} ---{styles.ENDC}\n")
+            print_md(data[key])
+
+    if "aggregated_result" in data:
+        print(
+            f"\n\n{styles.WARNING}{styles.BOLD}{styles.UNDERLINE}--- 📊 Overall Summary & Final Score ---{styles.ENDC}\n")
+        print_md(data["aggregated_result"])
+
+    print("\n" + "=" * 80 + "\n")
+
+

vendors/part1/final_state.json

@@ -0,0 +1,9 @@
+{
+    "student_essay": "One of the hot topics these day is about how the working week needs to be shorter and the need of longer weekends. However while I believe that people need to have enough time to rest after their working period, I don't think they need longer weekends to achieve that.\n\n\nFirstly, I think that there is plenty of time to rest after you get off from your work and prepare for the next day. Secondly, longer weekends will make people lazy and distant from their work. For example, when I was working at a tech company, we used to have 4 days off and when we would get back to work the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home. Thirdly, I read a recent study that discussed the impact of cutting working hours on the economy which showed massive damage to that country's economy in the long run.\n\n\nThere are several ways to improve your lifestyle while not having longer weekends. Most people tend to not plan their weekends at all and that can damage the quality of their time off. Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time. One of the best ways to make your job experience better is to find coworkers with the same interest as you. this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\n\n\nIn conclusion, I think while occasionally we need a time off from work to get into a better head space, there are other ways to tackle this problem without the need of cutting working days and making the weekends longer.",
+    "original_question": "The working week should be shorter and workers should have a longer weekend.\n\nDo you agree or disagree. ",
+    "task_response": "**1. What You Did Well:**\nYou successfully identified the core topic of the question and presented a clear and consistent position (disagreement) from the introduction through to the conclusion. You provided several relevant arguments to support your stance, such as the potential for laziness, the economic impact of reduced working hours, and the idea that current time off is sufficient if managed well. Your use of a personal anecdote to illustrate the point about becoming distant from work was a good attempt at providing specific support.\n\n**2. What You Could Have Done Better:**\nWhile your position was clear, some of your supporting points could have been more directly and strongly linked to the central argument against a shorter working week and longer weekend. For example, the point about finding coworkers with similar interests, while a valid way to improve job experience, doesn't directly argue against the *need* for a shorter working week or longer weekend in terms of rest or productivity. Its connection to the prompt's core argument was a bit indirect. Additionally, your reference to a \"recent study\" about economic impact, while a strong point, lacked specificity, which can weaken its persuasive power in terms of Task Response.\n\n**3. What You Missed:**\nYou did not completely miss any part of the prompt. You clearly addressed the \"agree or disagree\" aspect and provided reasons for your stance. The areas for improvement relate more to the depth and directness of the development of some ideas rather than an omission of a task component.\n\n**4. Recommendations for Improvement:**\n*   Before writing, ensure that every main idea and supporting example you plan to include directly and unequivocally supports your overall position. Ask yourself: \"How does this specific point or example directly prove why I agree or disagree with the prompt?\"\n*   When using external evidence or studies, try to be more specific if possible (e.g., \"Research from [institution] suggests...\") or frame it as a widely accepted concept if specific details are unavailable (e.g., \"It is widely understood that...\"). Avoid vague references like \"I read a recent study.\"\n*   Elaborate more fully on your main points. For instance, when you state there's \"plenty of time to rest,\" expand on *how* that time can be effectively utilized to achieve the desired rest, rather than just stating the fact.\n\n**5. Suggested Edits to Your Original Text:**\n\n*   **Your Original Sentence:** \"Firstly, I think that there is plenty of time to rest after you get off from your work and prepare for the next day.\"\n    *   **Higher-Scoring Alternative for Task Response:** \"Firstly, I contend that the current working structure already provides ample opportunity for rest and recuperation. Individuals can effectively manage their evenings and existing weekends to engage in leisure activities, pursue hobbies, and spend quality time with family, thereby mitigating the need for an extended break.\"\n\n*   **Your Original Sentence:** \"Thirdly, I read a recent study that discussed the impact of cutting working hours on the economy which showed massive damage to that country's economy in the long run.\"\n    *   **Higher-Scoring Alternative for Task Response:** \"Furthermore, a significant concern is the potential negative impact on national economies. Economic analyses often indicate that a reduction in working hours can lead to decreased productivity, higher operational costs for businesses, and ultimately, a decline in overall economic output, posing a long-term threat to prosperity.\"\n\n*   **Your Original Sentence:** \"One of the best ways to make your job experience better is to find coworkers with the same interest as you. this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\"\n    *   **Higher-Scoring Alternative for Task Response:** \"Beyond simply extending leisure time, improving job satisfaction itself can significantly enhance overall well-being, thereby reducing the perceived need for a shorter working week. For instance, fostering a positive work environment and encouraging social connections among colleagues can make the workday more enjoyable and less draining. My own experience, where forming friendships with colleagues who shared common interests like soccer transformed a challenging period into a more positive one, illustrates how internal workplace dynamics can be more impactful than simply increasing time away from work.\"\n\n**6. Final Task Response Score:** 7",
+    "coherence_and_cohesion": "**1. What You Did Well:**\nYour essay was clearly organized into an introduction, body paragraphs, and a conclusion, which provides a basic structure for your ideas. You also attempted to use linking words to introduce your points within the first body paragraph.\n\n**2. What You Could Have Done Better:**\nThe primary weakness in your essay's Coherence and Cohesion lies in the organization of your body paragraphs. Your first body paragraph is very long and contains three distinct arguments, which makes it difficult for the reader to follow a single, developed idea. The logical progression between your first and second body paragraphs is also not entirely smooth, as the second paragraph introduces a new line of argument (alternatives to longer weekends) rather than directly developing the reasons against them. Furthermore, your use of cohesive devices is somewhat mechanical and repetitive.\n\n**3. Cohesion and Coherence Breakdown:**\n*   **Paragraphing:** Your first body paragraph is a significant issue. It attempts to present three separate main ideas (\"plenty of time to rest,\" \"longer weekends make people lazy,\" and \"impact on economy\") within a single paragraph. For greater clarity and to allow for proper development of each point, these should have been separated into individual paragraphs. The second body paragraph also contains two distinct ideas (planning weekends and finding like-minded colleagues) that could benefit from clearer separation or more explicit linking.\n*   **Linking Words:** You rely heavily on \"Firstly,\" \"Secondly,\" and \"Thirdly\" to introduce points within one long paragraph. While these are cohesive devices, their repetitive use in this manner makes the writing feel mechanical rather than fluid. There is an underuse of a wider range of more sophisticated linking words and phrases that could show more complex relationships between sentences and paragraphs (e.g., cause and effect, contrast, further addition, exemplification). The transition from the first body paragraph to the second is abrupt, lacking a clear linking phrase to signal the shift in focus.\n*   **Referencing:** Referencing is generally clear (e.g., \"this\" referring to finding coworkers with the same interest). However, some phrasing like \"I was feeling distant with my job and felt the urge to be done with the work\" could be more concise to avoid slight repetition.\n\n**4. Recommendations for Improvement:**\n*   **Plan your paragraphs carefully:** Before you start writing, create a brief outline. Assign one central idea to each body paragraph. This will help you ensure that each paragraph has a clear topic sentence and develops a single argument thoroughly.\n*   **Vary your cohesive devices:** Expand your repertoire of linking words and phrases. Instead of just \"Secondly,\" consider using alternatives like \"Furthermore,\" \"Moreover,\" \"In addition to this,\" or \"Another significant point is that...\" to introduce new ideas. Use transition words to show the relationship between sentences (e.g., \"consequently,\" \"as a result,\" \"in contrast,\" \"however,\" \"for instance\").\n*   **Ensure logical progression between paragraphs:** Think about how each paragraph connects to the one before it and how it contributes to your overall argument. Use clear topic sentences and transitional phrases at the beginning of paragraphs to guide the reader smoothly from one idea to the next. For an \"agree/disagree\" essay, ensure your body paragraphs consistently support your stated stance.\n\n**5. Suggested Edits to Your Original Text:**\n\n*   **Original Body Paragraph 1:**\n    \"Firstly, I think that there is plenty of time to rest after you get off from your work and prepare for the next day. Secondly, longer weekends will make people lazy and distant from their work. For example, when I was working at a tech company, we used to have 4 days off and when we would get back to work the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home. Thirdly, I read a recent study that discussed the impact of cutting working hours on the economy which showed massive damage to that country's economy in the long run.\"\n\n*   **Higher-Scoring Alternative for Coherence and Cohesion (showing improved paragraphing and linking):**\n\n    \"To begin with, I believe that the current working week already provides sufficient time for individuals to rest and prepare for the following day. There is ample opportunity within the existing structure for personal rejuvenation without the need for extended weekends.\n\n    **Moreover,** a key concern is that longer weekends could inadvertently lead to a decline in productivity and a sense of detachment from one's profession. **For example,** during my experience at a tech company where we occasionally had four-day weekends, I observed that upon returning to work, both I and my colleagues often felt a diminished connection to our tasks, leading to a desire to complete work as quickly as possible rather than engaging deeply.\n\n    **Beyond individual impact,** there are significant economic considerations. I recently read a study that highlighted the substantial long-term damage inflicted upon a country's economy when working hours were significantly reduced, suggesting that such policies can have far-reaching negative consequences.\"\n\n*   **Original Body Paragraph 2:**\n    \"There are several ways to improve your lifestyle while not having longer weekends. Most people tend to not plan their weekends at all and that can damage the quality of their time off. Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time. One of the best ways to make your job experience better is to find coworkers with the same interest as you. this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\"\n\n*   **Higher-Scoring Alternative for Coherence and Cohesion (showing better linking and potential splitting):**\n\n    \"Instead of shortening the working week, there are alternative strategies to enhance one's lifestyle and well-being. **Crucially,** effective time management during existing weekends can significantly improve their quality. Many individuals fail to plan their time off, which often diminishes its restorative potential; conversely, thoughtful planning can lead to more fulfilling and productive leisure.\n\n    **Furthermore,** fostering positive social connections within the workplace can dramatically improve job satisfaction, thereby reducing the perceived need for longer breaks. This was certainly true in my own experience: after a challenging period at work, I connected with a colleague who shared my passion for soccer. Our discussions on various topics not only made the working environment more enjoyable but also fostered a stronger sense of belonging, making the work experience much more positive for both of us.\"\n\n**6. Final Coherence and Cohesion Score:** 5",
+    "lexical_resource": "**1. What You Did Well:**\nYou have used some basic topic-specific vocabulary related to work and leisure, such as 'working week', 'weekends', 'time off', and 'economy'. You also attempted to use some phrases to express your opinion, like 'I believe that' and 'I don't think'.\n\n**2. What You Could Have Done Better:**\nThe essay relies heavily on a limited range of vocabulary, leading to repetition and a lack of precision. Many phrases are informal or colloquial, which is not appropriate for an academic essay. There is a consistent lack of sophisticated vocabulary and an absence of less common lexical items. Word choice and collocations are frequently unnatural, making the text sound less fluent and professional.\n\n**3. Lexical Resource Breakdown:**\n\n*   **Repetition:**\n    *   The word \"work/working\" is used excessively (e.g., \"working week,\" \"working period,\" \"get off from your work,\" \"back to work,\" \"my job,\" \"the work,\" \"working hours,\" \"at work,\" \"working experience,\" \"from work,\" \"working days\").\n    *   \"Time\" is repeated frequently (e.g., \"enough time,\" \"plenty of time,\" \"time off,\" \"quality time\").\n    *   \"Better\" is overused (e.g., \"better use,\" \"make your job experience better,\" \"better for both of us,\" \"better head space\").\n    *   \"Need\" is repeated (e.g., \"needs to be shorter,\" \"need of longer weekends,\" \"people need to have,\" \"we need a time off,\" \"without the need of cutting\").\n    *   \"Feel/feeling\" is repeated in the same sentence: \"didn't feel the same as I was feeling distant.\"\n\n*   **Word Choice/Collocation:**\n    *   \"hot topics these day\" - \"these days\" is correct, but \"hot topics\" is informal. Consider \"a widely debated issue\" or \"a prominent discussion point.\"\n    *   \"the need of longer weekends\" - Should be \"the need *for* longer weekends.\"\n    *   \"get off from your work\" - More natural would be \"finish work\" or \"leave work.\"\n    *   \"make people lazy and distant from their work\" - \"Foster laziness and detachment from their professional responsibilities\" would be more precise. \"Distant from their work\" is awkward.\n    *   \"the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job\" - Very repetitive and unnatural. Consider \"I felt a diminished connection to my role and colleagues, experiencing a sense of detachment.\"\n    *   \"felt the urge to be done with the work as quickly as possible\" - \"Felt compelled to complete tasks swiftly.\"\n    *   \"massive damage to that country's economy\" - \"Massive damage\" is informal. Use \"significant detriment\" or \"severe adverse impact.\"\n    *   \"improve your lifestyle while not having longer weekends\" - \"Enhance one's lifestyle without necessarily extending weekends.\"\n    *   \"damage the quality of their time off\" - \"Detract from the quality of their leisure time.\"\n    *   \"Good planning will guide you to find better use of you quality time\" - \"Effective planning can enable individuals to make better use of their leisure time.\" (\"you quality time\" is a grammatical error, should be \"your\").\n    *   \"make your job experience better\" - \"Enhance one's professional experience.\"\n    *   \"having a rough few weeks at work\" - \"Rough\" is informal. Consider \"experiencing a challenging period at work.\"\n    *   \"discuss about our opinion\" - \"Discuss our opinion\" (no \"about\").\n    *   \"get into a better head space\" - \"Head space\" is informal. Consider \"achieve a more positive mental state\" or \"improve one's well-being.\"\n    *   \"tackle this problem\" - \"Address this issue\" or \"resolve this challenge.\"\n\n*   **Spelling/Word Formation:**\n    *   \"these day\" (should be \"these days\")\n    *   \"you quality time\" (should be \"your quality time\")\n\n**4. Recommendations for Improvement:**\n*   **Expand your vocabulary range:** Actively learn synonyms and antonyms for common words. For example, instead of just \"good\" or \"bad,\" learn \"beneficial,\" \"detrimental,\" \"advantageous,\" \"adverse,\" etc.\n*   **Focus on precision:** Choose words that convey your meaning exactly. For instance, instead of \"big problem,\" use \"significant issue\" or \"major challenge.\"\n*   **Improve collocation awareness:** Pay attention to how words naturally go together. Use a collocation dictionary or notice common phrases in authentic English texts. For example, \"make a decision,\" not \"do a decision.\"\n*   **Elevate your style:** Avoid informal language and colloquialisms in academic writing. Replace phrases like \"get off from your work\" or \"rough few weeks\" with more formal alternatives.\n*   **Practice paraphrasing:** When you write, try to rephrase ideas using different vocabulary to avoid repetition.\n\n**5. Suggested Edits to Your Original Text:**\n\n*   *Your Original Text:* \"One of the hot topics these day is about how the working week needs to be shorter and the need of longer weekends.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"**A prominent discussion point** currently revolves around the **proposal for a shorter working week** and the **extension of weekends**.\"\n\n*   *Your Original Text:* \"I think that there is plenty of time to rest after you get off from your work and prepare for the next day.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"I believe that individuals have **ample opportunity for recuperation** after **concluding their workdays** to prepare for the subsequent one.\"\n\n*   *Your Original Text:* \"longer weekends will make people lazy and distant from their work.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"Extended weekends could **foster indolence** and **detachment from one's professional responsibilities**.\"\n\n*   *Your Original Text:* \"the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"I experienced a **diminished connection** to my role and colleagues, feeling **disengaged** and **compelled to complete tasks swiftly** in order to return home.\"\n\n*   *Your Original Text:* \"cutting working hours on the economy which showed massive damage to that country's economy in the long run.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"reducing working hours on the economy, which indicated **significant detriment** to that nation's economy in the long run.\"\n\n*   *Your Original Text:* \"Most people tend to not plan their weekends at all and that can damage the quality of their time off. Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"Many individuals often **neglect to plan their weekends effectively**, which can **detract from the quality of their leisure time**. **Strategic planning** can enable them to **optimise their free time** and establish achievable goals within a defined period.\"\n\n*   *Your Original Text:* \"occasionally we need a time off from work to get into a better head space, there are other ways to tackle this problem without the need of cutting working days and making the weekends longer.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"while occasional **breaks from work** are necessary to **achieve a more positive mental state**, alternative strategies exist to **address this issue** without the necessity of reducing working days or extending weekends.\"\n\n**6. Final Lexical Resource Score:** 5",
+    "grammatical_range_and_accuracy": "**1. What You Did Well:**\nYou have demonstrated a good attempt at using a mix of simple, compound, and complex sentence structures. There is clear evidence of complex sentences, particularly those using subordinate clauses (e.g., \"while I believe that...\", \"when I was working...\") and relative clauses (e.g., \"that discussed...\", \"who also loved...\"). This shows a good range in your grammatical structures. You also successfully use introductory phrases and clauses, often followed by correct punctuation.\n\n**2. What You Could Have Done Better:**\nWhile you attempt complex structures, there are frequent grammatical errors that, though often minor, accumulate and affect overall accuracy. These errors include issues with articles, prepositions, singular/plural forms, and occasional tense inconsistencies. Some very long sentences become slightly unwieldy, indicating a need for more precise control over highly complex constructions and better punctuation to manage their flow.\n\n**3. Grammatical Range and Accuracy Breakdown:**\n*   **Sentence Structure:** You effectively use a variety of sentence types, moving beyond simple sentences to incorporate complex ones. This includes sentences with noun clauses (\"how the working week needs to be shorter\"), adverbial clauses of time and concession (\"when I was working...\", \"while I believe...\"), and relative clauses (\"that discussed...\", \"who also loved...\"). This demonstrates a good range. However, some sentences are excessively long, which can lead to awkward phrasing and a slight loss of clarity, suggesting that while you attempt complex structures, full control over their most intricate forms is still developing.\n*   **Grammatical Errors:**\n    *   **Articles:** You sometimes omit or misuse articles, for example, \"a time off\" should be \"time off.\"\n    *   **Prepositions:** There are recurring errors with prepositions, such as \"the need of longer weekends\" (should be \"the need for\"), \"get off from your work\" (should be \"get off work\"), \"distant with my job\" (should be \"distant from my job\"), and \"discuss about our opinion\" (should be \"discuss our opinion\").\n    *   **Singular/Plural:** You used \"these day\" instead of \"these days\" and \"our opinion on different topics\" instead of \"our opinions on different topics.\"\n    *   **Tense Consistency:** In the sentence \"so I can go back home,\" the present tense \"can\" is inconsistent with the past context of the narrative (\"when I was working...\"). It should be \"so that I could go back home.\"\n    *   **Word Choice/Phrasing:** Phrases like \"tend to not plan\" could be more naturally expressed as \"tend not to plan.\" \"use of you quality time\" should be \"use of your quality time.\"\n*   **Punctuation:**\n    *   You occasionally miss commas after introductory clauses (e.g., \"However while I believe...\" should be \"However, while I believe...\").\n    *   There is a significant run-on sentence due to a lack of capitalization and appropriate punctuation: \"this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\" This sentence is too long and should be broken up or use a semicolon.\n\n**4. Recommendations for Improvement:**\n*   **Focus on Prepositions and Articles:** Dedicate specific practice to common prepositional phrases and the rules for using 'a,' 'an,' and 'the,' especially with abstract nouns or general statements.\n*   **Review Singular/Plural Nouns:** Pay close attention to whether nouns should be singular or plural, particularly when referring to general concepts or multiple items.\n*   **Master Complex Sentence Punctuation:** Practice using commas correctly with dependent and independent clauses. Learn how to use semicolons to connect closely related independent clauses, or how to split very long sentences into two or more shorter, clearer ones.\n*   **Ensure Tense Consistency:** When narrating events or discussing past experiences, ensure that all verbs maintain a consistent tense unless there's a specific reason for a shift.\n*   **Proofread Systematically:** After writing, review your essay specifically for one type of grammatical error at a time (e.g., first check all prepositions, then all articles, then all subject-verb agreements).\n\n**5. Suggested Edits to Your Original Text:**\n*   **Your Original Text:** \"One of the hot topics these day is about how the working week needs to be shorter and the need of longer weekends.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"One of the hot topics these **days** is **the debate about** how the working week needs to be shorter and the need **for** longer weekends.\"\n*   **Your Original Text:** \"However while I believe that people need to have enough time to rest after their working period, I don't think they need longer weekends to achieve that.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"However, while I believe that people need to have enough time to rest after their working period, I don't think they need longer weekends to achieve that.\"\n*   **Your Original Text:** \"For example, when I was working at a tech company, we used to have 4 days off and when we would get back to work the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"For example, when I was working at a tech company, we used to have four days off. When we returned to work, the connection I had with my job and colleagues didn't feel the same; I felt distant from my job and had the urge to finish work as quickly as possible so that I could go back home.\"\n*   **Your Original Text:** \"Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"Good planning will guide you to make better use of **your** quality time and to set the goals you want to achieve by a certain time.\"\n*   **Your Original Text:** \"this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"**This** was the case for me: I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did. We used to discuss our **opinions** on different topics, which made the working experience much better for both of us.\"\n*   **Your Original Text:** \"In conclusion, I think while occasionally we need a time off from work to get into a better head space, there are other ways to tackle this problem without the need of cutting working days and making the weekends longer.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"In conclusion, I think while occasionally we need time off from work to get into a better headspace, there are other ways to tackle this problem without the need **for** cutting working days and making the weekends longer.\"\n\n**6. Final Grammatical Range and Accuracy Score:**\n6",
+    "aggregated_result": "**Overall IELTS Writing Task 2 Feedback**\n\nHere is a summary of your performance based on the four official IELTS scoring criteria.\n\n**1. Task Response**\n*   **Strengths:** You clearly identified the core topic and maintained a consistent position of disagreement throughout the essay. You provided several relevant arguments, such as the potential for laziness, economic impact, and the sufficiency of current time off. The attempt to use a personal anecdote for illustration was also noted.\n*   **Areas for Improvement:** Some supporting points could have been more directly linked to the central argument against a shorter working week. The connection of finding similar-interest coworkers to the prompt's core argument was indirect. Additionally, the reference to a \"recent study\" lacked specificity, which weakened its persuasive power.\n*   **Expert Score:** 7\n\n**2. Coherence and Cohesion**\n*   **Strengths:** Your essay demonstrated a clear basic structure with an introduction, body paragraphs, and a conclusion. You also attempted to use linking words to introduce points within the first body paragraph.\n*   **Areas for Improvement:** The primary weakness was the organization of body paragraphs, particularly the first, which was excessively long and contained three distinct arguments. The logical progression between the first and second body paragraphs was not smooth, and the use of cohesive devices was somewhat mechanical and repetitive.\n*   **Expert Score:** 5\n\n**3. Lexical Resource (Vocabulary)**\n*   **Strengths:** You used some basic topic-specific vocabulary related to work and leisure. You also attempted to use phrases to express your opinion.\n*   **Areas for Improvement:** The essay relied on a limited vocabulary range, leading to repetition and a lack of precision. Many phrases were informal or colloquial, which is not appropriate for academic writing. There was a consistent absence of sophisticated vocabulary and less common lexical items, and word choice and collocations were frequently unnatural.\n*   **Expert Score:** 5\n\n**4. Grammatical Range and Accuracy**\n*   **Strengths:** You demonstrated a good attempt at using a mix of simple, compound, and complex sentence structures, including subordinate and relative clauses. You also successfully used introductory phrases and clauses, often with correct punctuation.\n*   **Areas for Improvement:** Despite attempts at complex structures, frequent grammatical errors accumulated, affecting overall accuracy. These included issues with articles, prepositions, singular/plural forms, and occasional tense inconsistencies. Some very long sentences became unwieldy, indicating a need for more precise control over complex constructions and better punctuation.\n*   **Expert Score:** 6\n\n---\n\n**Final Analysis and Overall Score**\n*   **Summative Comments:** Overall, your ability to present a clear position and attempt a range of sentence structures are notable strengths. However, your final score is primarily limited by issues in Coherence and Cohesion, particularly paragraphing, and a restricted range of vocabulary with frequent errors in word choice and collocation. Grammatical accuracy, especially with prepositions and articles, also requires attention.\n*   **Overall Band Score:** 6.0"
+}

vendors/part1/main.py

@@ -0,0 +1,81 @@
+# part1/main.py
+import base64
+import io
+import sys
+import os
+
+# --- Assuming these are your existing, correct imports from your project ---
+from .nodes import task_response, coherence_and_cohesion, lexical_resource, grammatical_range_and_accuracy, aggregator
+from .state import State
+from .workflow import workflow_fn
+from .display_report import display_report_fn
+
+
+def encode_image(image_path: str) -> str:
+    """Encodes an image file to a base64 string."""
+    with open(image_path, "rb") as image_file:
+        return base64.b64encode(image_file.read()).decode('utf-8')
+
+
+def run_ielts_part1_agent(image_path: str, student_essay: str) -> str:
+    """
+    Runs the IELTS Part 1 agent with an image and text, returning the report as a string.
+    """
+    # 1. Encode the image provided by the user
+    base64_image = encode_image(image_path)
+    image_url = f"data:image/jpeg;base64,{base64_image}"  # Use jpeg as a common format
+
+    # 2. Set up the initial state for the agentic workflow
+    initial_state = {
+        "image_url": image_url,
+        "student_essay": student_essay
+    }
+
+    # 3. Initialize the LangGraph workflow
+    final_workflow = workflow_fn(State, task_response, lexical_resource, grammatical_range_and_accuracy,
+                                 coherence_and_cohesion, aggregator)
+
+    # 4. Invoke the agent
+    print("Invoking Part 1 agent workflow...")
+    final_state = final_workflow.invoke(initial_state)
+    print("Workflow complete.")
+
+    # 5. Capture the printed output of your display_report_fn
+    # This redirects the console output to a string variable
+    old_stdout = sys.stdout
+    sys.stdout = captured_output = io.StringIO()
+
+    display_report_fn(final_state)
+
+    sys.stdout = old_stdout  # Restore the standard output
+    report_string = captured_output.getvalue()  # Get the report from the string buffer
+
+    # 6. Return the captured report as a string
+    return report_string
+
+
+# This part is for your own direct testing of this script
+if __name__ == "__main__":
+    # To test this, you need a dummy image file named "task_image.png"
+    # in the same directory.
+    if not os.path.exists("task_image.png"):
+        print("Creating a dummy 'task_image.png' for testing.")
+        try:
+            from PIL import Image, ImageDraw
+
+            img = Image.new('RGB', (300, 150), color=(73, 109, 137))
+            d = ImageDraw.Draw(img)
+            d.text((10, 10), "Test Image for Part 1", fill=(255, 255, 0))
+            img.save('task_image.png')
+        except ImportError:
+            print("Please install Pillow (`pip install Pillow`) to create a test image.")
+            sys.exit(1)
+
+    test_image_path = "task_image.png"
+    test_essay = """The provided image shows a simple graph. From 1990 to 2010, the data increased significantly. This indicates a positive trend over the two decades shown in the chart."""
+
+    print("--- Running standalone test for Part 1 ---")
+    result = run_ielts_part1_agent(test_image_path, test_essay)
+    print("\n--- Agent Result ---")
+    print(result)
+

vendors/part1/model.py

@@ -0,0 +1,5 @@
+from langchain_google_genai import ChatGoogleGenerativeAI
+from dotenv import load_dotenv
+
+load_dotenv()
+model = ChatGoogleGenerativeAI(model='gemini-2.5-flash-preview-05-20', temperature=0.1, top_p=0.95)

vendors/part1/nodes.py

@@ -0,0 +1,436 @@
+from .state import State
+from langchain_core.prompts import ChatPromptTemplate, SystemMessagePromptTemplate, HumanMessagePromptTemplate
+from .model import model
+import logging
+
+logger = logging.getLogger(__name__)
+
+def task_response(state: State):
+    print("--Starting Task Response Analysis--")
+    logger.info("Starting Task Response Analysis")
+    
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner specializing in **Task 1 (Academic) Task Response**. Your sole function is to assess a student's report based *only* on the **Task Response** criterion. You will be given an image (e.g., a chart, graph, table, diagram, or map) and the student's written report. You must ignore all other scoring criteria (Coherence & Cohesion, Lexical Resource, Grammatical Range & Accuracy). Your analysis must focus exclusively on how fully and accurately the student has described the information presented in the visual.
+
+            **Your Role and How to Score Task Response (Task 1):**
+
+            Your primary job is to evaluate if the student has fulfilled the task requirements by accurately summarizing and reporting the key features of the visual data.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Introduction:** Does the introduction correctly paraphrase the purpose of the visual information?
+            2.  **Overview (Crucial):** Is there a clear and accurate summary of the main trends, differences, or stages? This is essential for a score of Band 6 or higher. The overview should synthesize the most significant information, not list details.
+            3.  **Key Feature Selection:** Has the student identified and focused on the most important and relevant information and trends from the visual? Or have they tried to describe every single detail mechanically?
+            4.  **Data Accuracy:** Is the data (numbers, percentages, dates, units) reported accurately as it appears in the visual?
+            5.  **Completeness:** Does the report cover all necessary parts of the visual? For tasks with multiple visuals (e.g., two charts), are both addressed?
+            6.  **No Inappropriate Information:** Has the student avoided including personal opinions, conclusions, or information that is not explicitly present in the visual? The task is to describe, not interpret or speculate.
+
+            **Task Response (Task 1) Scoring Guide (Strictly follow this):**
+            * **Band 7+:** The response covers all requirements of the task. It presents a clear, accurate, and comprehensive overview of the main trends/features. Key features are clearly presented, highlighted, and supported by accurate data.
+            * **Band 6:** The response addresses the task requirements. It presents an overview, but it may be insufficiently clear or comprehensive. Key features are presented, but some may be inadequately covered or details may be irrelevant.
+            * **Band 5:** The response attempts to address the task but only covers the requirements partially. There is no clear overview. Key features are inadequately covered, and there may be inaccuracies in the data.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+               Start with positive reinforcement. For example, "You successfully paraphrased the prompt in your introduction and correctly identified some of the key data points."
+
+            **2. What You Could Have Done Better:**
+               Provide a detailed critique. For example, "Your report lacked a clear overview paragraph summarizing the main trends. This is a critical feature and its absence limits your score." or "You attempted to describe every number on the chart, which is not the goal; you should select and group the key features instead."
+
+            **3. What You Missed:**
+               Clearly state any parts of the task that were ignored. For example, "You described the data for the USA and Japan but completely omitted the data for Canada, which was part of the chart." or "You included a conclusion with your personal opinion, which is not required or appropriate for Task 1."
+
+            **4. Recommendations for Improvement:**
+               Give actionable advice. For instance, "Always write a dedicated overview paragraph after your introduction that summarizes the 2-4 most significant things you see in the visual *before* you start describing details. Ask yourself: What is the biggest change? What is the highest point? What is the most obvious comparison?"
+
+            **5. Suggested Edits to Your Original Text:**
+               Provide specific, revised sentences or a paragraph showing how to improve.
+               *Example:*
+               *Your Original Text:* "The graph shows sales. In 2000, sales were 20 million. In 2001, sales were 25 million."
+               *Higher-Scoring Alternative for Task Response (Overview):* "Overall, it is clear that sales for the product experienced a significant upward trend over the period, while also displaying some minor fluctuations from year to year."
+
+            **6. Final Task Response Score:**
+               Conclude with the final band score for Task Response only.
+               *Example:*
+               "Final Task Response Score: 6"
+
+            Do not add any conversational closings, greetings, or encouragement to message again.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template([
+            {
+                "type": "text",
+                "text": """**IELTS Writing Task 1 (Academic)**
+
+        Please evaluate the following student response based on the provided image.
+
+        **Student's Response:**
+        {student_response}"""
+            },
+            {
+                "type": "image_url",
+                "image_url": "{image_url}",
+            }
+        ])
+    ])
+
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "image_url": state["image_url"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"task_response": response.content}
+
+
+def coherence_and_cohesion(state: State):
+    print("--Starting CC Analysis--")
+    logger.info("Starting CC Analysis")
+    
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner specializing in **Task 1 (Academic) Coherence and Cohesion**. Your sole function is to assess a student's report based *only* on its organization, paragraphing, and the linking of information. You will be given an image and the student's written report. You must ignore all other scoring criteria (Task Response, Lexical Resource, Grammatical Range and Accuracy). Your analysis must focus exclusively on the logical flow and structure of the report.
+
+            **Your Role and How to Score Coherence and Cohesion (Task 1):**
+
+            Your primary job is to evaluate how the report is organized and how the information is linked. Coherence is the logical sequencing of information, while Cohesion is the use of linguistic devices to connect it.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Logical Organization:** Is the information grouped logically in paragraphs? For example, grouping by time periods, by categories (countries, age groups), or by trends (increasing items in one paragraph, decreasing in another).
+            2.  **Paragraphing:** Does the report use paragraphs effectively? Is there a clear introduction, overview, and body paragraphs? Are paragraphs focused on a specific feature or set of features?
+            3.  **Progression:** Can the reader easily follow the description from one point to the next? Is the information presented in a logical order?
+            4.  **Cohesive Devices:** Does the student use a range of linking words and phrases appropriate for Task 1 (e.g., 'In contrast,' 'Similarly,' 'Turning to the details,' 'As can be seen from the graph')? Are they used accurately and without being overly mechanical?
+            5.  **Referencing:** Is the use of pronouns (e.g., 'it,' 'its,' 'the former,' 'the latter') clear and unambiguous, helping to avoid repetition?
+
+            **Coherence and Cohesion (Task 1) Scoring Guide (Strictly follow this):**
+            * **Band 7+:** Information is logically organized with clear progression. A range of cohesive devices is used effectively. Paragraphing is logical and sufficient.
+            * **Band 6:** Information is arranged coherently with a mostly clear progression. Cohesive devices are used, but they may be faulty or mechanical. Paragraphing may not always be logical.
+            * **Band 5:** There is some organization, but it's not always logical and may lack overall progression. Cohesive devices may be inadequate, inaccurate, or overused. Paragraphing may be inadequate.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+               Start with positive reinforcement on the structure. For example, "Your report was organized into paragraphs, which provides a basic structure for your description."
+
+            **2. What You Could Have Done Better:**
+               Provide a detailed critique. For example, "The information was not grouped logically. You switched between describing two different countries within the same paragraph, which was confusing. It would be clearer to dedicate one paragraph to each country."
+
+            **3. Cohesion and Coherence Breakdown:**
+               * **Paragraphing:** Comment on the paragraph structure. Example: "Your second body paragraph was very long and mixed rising and falling trends. It would have been more coherent to discuss the rising figures in one paragraph and the falling figures in another."
+               * **Linking Words:** Comment on cohesive devices. Example: "You used 'Also' three times to start a sentence. Using more varied linkers like 'Furthermore' or 'In addition,' or comparative language like 'In contrast,' would improve the flow."
+
+            **4. Recommendations for Improvement:**
+               Give actionable advice. For instance, "Before writing, create a simple plan. Decide how you will group the information from the chart into 2-3 body paragraphs. This will ensure your report is logical and easy for the reader to follow."
+
+            **5. Suggested Edits to Your Original Text:**
+               Provide specific, revised sentences showing improved flow.
+               *Example:*
+               *Your Original Text:* "Car sales were high. Bike sales were low. Car sales went up. Bike sales went down."
+               *Higher-Scoring Alternative for Coherence and Cohesion:* "Car sales started at a high level and subsequently increased throughout the period. **In stark contrast,** the figures for bike sales were initially low and experienced a consistent decline."
+
+            **6. Final Coherence and Cohesion Score:**
+               Conclude with the final band score for Coherence and Cohesion only.
+               *Example:*
+               "Final Coherence and Cohesion Score: 6"
+
+            Do not add any conversational closings, greetings, or encouragement to message again.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template([
+            {
+                "type": "text",
+                "text": """**IELTS Writing Task 1 (Academic)**
+
+        Please evaluate the following student response based on the provided image.
+
+        **Student's Response:**
+        {student_response}"""
+            },
+            {
+                "type": "image_url",
+                "image_url": "{image_url}",
+            }
+        ])
+    ])
+    
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "image_url": state["image_url"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"coherence_and_cohesion": response.content}
+
+
+def lexical_resource(state: State):
+    print("--Starting Lexical Resource Analysis--")
+    logger.info("Starting Lexical Resource Analysis")
+    
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner specializing in **Task 1 (Academic) Lexical Resource**. Your sole function is to assess a student's report based *only* on the range, accuracy, and appropriacy of the vocabulary used to describe visual data. You will be given an image and the student's written report. You must ignore all other scoring criteria (Task Response, Coherence & Cohesion, Grammatical Range & Accuracy).
+
+            **Your Role and How to Score Lexical Resource (Task 1):**
+
+            Your primary job is to evaluate the writer's vocabulary, particularly the language used to describe trends, make comparisons, and present data.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Range of Vocabulary:** Does the writer use varied and precise vocabulary for trends (e.g., 'rose sharply,' 'declined steadily,' 'fluctuated,' 'peaked at,' 'reached a nadir')? Or do they repeat simple words like 'go up' and 'go down'?
+            2.  **Vocabulary for Comparison:** Is there a good range of comparative language (e.g., 'significantly higher than,' 'three times as much as,' 'followed by,' 'the respective figures for')?
+            3.  **Precision:** Are words used accurately? For example, using 'dramatic' for a large change and 'slight' for a small one.
+            4.  **Collocations:** Does the writer use natural word pairings (e.g., 'a sharp increase,' 'a gradual decline')?
+            5.  **Spelling and Word Formation:** Are there errors in spelling or word formation (e.g., 'increase' (n.) vs 'increasing' (adj.))? Do these errors impede communication?
+
+            **Lexical Resource (Task 1) Scoring Guide (Strictly follow this):**
+            * **Band 7+:** Uses a sufficient range of vocabulary with flexibility and precision. Uses some less common lexical items, with an awareness of style and collocation (e.g., 'a corresponding fall,' 'plateaued'). May produce occasional minor errors.
+            * **Band 6:** Uses an adequate range of vocabulary for the task. Attempts to use less common vocabulary but with some inaccuracy. Makes some errors in spelling/word formation, but they do not impede communication.
+            * **Band 5:** Uses a limited range of vocabulary, but it is minimally adequate. Makes noticeable errors that may cause some difficulty for the reader.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+               Start with positive reinforcement. For example, "You have correctly used some basic vocabulary to describe trends, such as 'increased' and 'decreased'."
+
+            **2. What You Could Have Done Better:**
+               Provide a detailed critique. For example, "The report was repetitive. You used the word 'increased' five times. To show a wider range, you could have used synonyms like 'rose,' 'grew,' 'climbed,' or phrases like 'saw an upward trend'."
+
+            **3. Lexical Resource Breakdown:**
+               * **Repetition:** List overused words. Example: "The word 'number' was used frequently. Alternatives like 'figure,' 'quantity,' or 'proportion' could have been used."
+               * **Word Choice/Collocation:** Point out specific errors. Example: "The phrase 'a big jump' is too informal. A better choice would be 'a significant increase' or 'a sharp rise'."
+
+            **4. Recommendations for Improvement:**
+               Give actionable advice. For instance, "Create vocabulary lists specifically for Task 1. Have one list for 'up' words (increase, rise, grow, climb, rocket, surge), one for 'down' words (decrease, fall, decline, drop, plunge), one for stability (remain stable, plateau), and one for fluctuation."
+
+            **5. Suggested Edits to Your Original Text:**
+               Provide specific, revised sentences showing better vocabulary.
+               *Example:*
+               *Your Original Text:* "The number of sales went up a lot from 20 to 80."
+               *Higher-Scoring Alternative for Lexical Resource:* "The figure for sales experienced **a dramatic fourfold increase,** **climbing** from 20 to 80."
+
+            **6. Final Lexical Resource Score:**
+               Conclude with the final band score for Lexical Resource only.
+               *Example:*
+               "Final Lexical Resource Score: 6"
+
+            Do not add any conversational closings, greetings, or encouragement to message again.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template([
+            {
+                "type": "text",
+                "text": """**IELTS Writing Task 1 (Academic)**
+
+        Please evaluate the following student response based on the provided image.
+
+        **Student's Response:**
+        {student_response}"""
+            },
+            {
+                "type": "image_url",
+                "image_url": "{image_url}",
+            }
+        ])
+    ])
+    
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "image_url": state["image_url"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"lexical_resource": response.content}
+
+
+def grammatical_range_and_accuracy(state: State):
+    print("--Starting Grammar Analysis--")
+    logger.info("Starting Grammar Analysis")
+    
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner specializing in **Task 1 (Academic) Grammatical Range and Accuracy (GRA)**. Your sole function is to assess a student's report based *only* on the variety, complexity, and correctness of the grammatical structures used. You will be given an image and the student's written report. You must ignore all other scoring criteria (Task Response, Coherence & Cohesion, Lexical Resource).
+
+            **Your Role and How to Score Grammatical Range and Accuracy (Task 1):**
+
+            Your primary job is to analyze the writer's control and use of grammar, paying special attention to structures used for describing and comparing data.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Sentence Structures:** Does the writer use a mix of simple, compound, and complex sentences? Is there an over-reliance on simple 'Subject-Verb-Object' sentences?
+            2.  **Grammatical Range:** Is there a variety of structures relevant to Task 1? For example:
+                * Language of comparison (e.g., 'was higher than', 'was not as high as').
+                * Use of different clauses (e.g., "..., while the figure for Y fell.", "..., which was followed by a sharp decline.").
+                * Correct tense usage (e.g., past tense for past charts, present perfect for changes up to now, future for projections).
+            3.  **Grammatical Accuracy:** How frequent and severe are grammatical errors (e.g., subject-verb agreement, articles, prepositions)? Do they impede communication?
+            4.  **Punctuation:** Is punctuation used correctly to support sentence structure and clarity?
+
+            **Grammatical Range and Accuracy (Task 1) Scoring Guide (Strictly follow this):**
+            * **Band 7+:** Uses a variety of complex structures effectively. Produces frequent error-free sentences. Has good control of grammar and punctuation, with only a few errors.
+            * **Band 6:** Uses a mix of simple and complex sentence forms. Makes some errors in grammar and punctuation, but they rarely reduce communication.
+            * **Band 5:** Uses only a limited range of structures. Attempts complex sentences, but they are often inaccurate. Makes frequent grammatical errors that can cause some difficulty for the reader.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+               Start with positive reinforcement. For example, "You have correctly used the simple past tense throughout your report, which is appropriate for the time frame of the chart."
+
+            **2. What You Could Have Done Better:**
+               Provide a detailed critique. For example, "The report consisted mainly of short, simple sentences. To improve your range, you should combine ideas using conjunctions like 'while' or 'whereas' to make comparisons within a single sentence."
+
+            **3. Grammatical Range and Accuracy Breakdown:**
+               * **Sentence Structure:** Comment on the variety. Example: "You wrote: 'Sales in the UK were 50. Sales in France were 30.' These could be combined into one complex sentence: 'Sales in the UK were 50, whereas the figure for France was significantly lower at 30.'"
+               * **Grammatical Errors:** List repeated errors. Example: "There were several errors with prepositions, such as 'increased at 50%' instead of 'increased by 50%' and 'sales in 2005' instead of 'in the year 2005'."
+
+            **4. Recommendations for Improvement:**
+               Give actionable advice. For instance, "Practice writing sentences that compare two data points. Learn the difference between using a verb + adverb (e.g., 'increased sharply') and an adjective + noun (e.g., 'there was a sharp increase')."
+
+            **5. Suggested Edits to Your Original Text:**
+               Provide specific, revised sentences showing better grammar.
+               *Example:*
+               *Your Original Text:* "The UK had the highest number. It was 50%."
+               *Higher-Scoring Alternative for Grammatical Range and Accuracy:* "The UK accounted for the highest proportion of sales, **at 50%**, **which was double the figure for the next largest country.**"
+
+            **6. Final Grammatical Range and Accuracy Score:**
+               Conclude with the final band score for GRA only.
+               *Example:*
+               "Final Grammatical Range and Accuracy Score: 5"
+
+            Do not add any conversational closings, greetings, or encouragement to message again.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template([
+            {
+                "type": "text",
+                "text": """**IELTS Writing Task 1 (Academic)**
+
+        Please evaluate the following student response based on the provided image.
+
+        **Student's Response:**
+        {student_response}"""
+            },
+            {
+                "type": "image_url",
+                "image_url": "{image_url}",
+            }
+        ])
+    ])
+
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "image_url": state["image_url"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"grammatical_range_and_accuracy": response.content}
+
+
+def aggregator(state: State):
+    print("--Summarizing--")
+    logger.info("Summarizing: starting")
+    
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are a Senior IELTS Writing Assessor and Head Examiner. Your function is to receive four separate, detailed evaluations for a single **IELTS Writing Task 1 (Academic)** report and synthesize them into a final, holistic report for the student. The four evaluations you will receive correspond to the four official IELTS marking criteria: Task Response (TR), Coherence and Cohesion (C&C), Lexical Resource (LR), and Grammatical Range and Accuracy (GRA).
+
+            **Your Core Role and Directives:**
+
+            1.  **Synthesize, Do Not Re-evaluate:** You must base your entire report *only* on the analysis and scores provided in the four expert reports you receive as input. Do NOT re-examine the student's original report or the visual data. You are to trust and summarize the findings of the specialist examiners.
+            2.  **Summarize Key Points:** For each of the four criteria, concisely summarize the main strengths and the key areas for improvement identified by the specialist examiner.
+            3.  **Calculate the Overall Score:** You must calculate the final, overall IELTS band score for Writing Task 1 precisely according to the official method.
+
+            **How to Calculate the Overall Band Score (Crucial Instructions):**
+
+            The Overall Band Score is the average of the four individual scores. Follow this procedure exactly:
+            * **Formula:** Overall Score = (Task Response Score + Coherence and Cohesion Score + Lexical Resource Score + Grammatical Range and Accuracy Score) / 4
+            * **Official Rounding Rule:** The result must be rounded to the nearest half-band.
+                * If the average ends in **.25**, round **UP** to the next half-band (e.g., an average of 6.25 becomes an Overall Score of **6.5**).
+                * If the average ends in **.75**, round **UP** to the next whole band (e.g., an average of 6.75 becomes an Overall Score of **7.0**).
+                * Averages ending in .0 or .5 remain unchanged.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a single, consolidated report in the following order and with these exact headings:
+
+            **Overall IELTS Writing Task 1 (Academic) Feedback**
+
+            Here is a summary of your performance based on the four official IELTS scoring criteria.
+
+            **1. Task Response**
+            * **Strengths:** [Concisely summarize the positive points from the Task Response agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Task Response agent's report.]
+            * **Expert Score:** [State the score given by the Task Response agent.]
+
+            **2. Coherence and Cohesion**
+            * **Strengths:** [Concisely summarize the positive points from the Coherence and Cohesion agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Coherence and Cohesion agent's report.]
+            * **Expert Score:** [State the score given by the Coherence and Cohesion agent.]
+
+            **3. Lexical Resource (Vocabulary)**
+            * **Strengths:** [Concisely summarize the positive points from the Lexical Resource agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Lexical Resource agent's report.]
+            * **Expert Score:** [State the score given by the Lexical Resource agent.]
+
+            **4. Grammatical Range and Accuracy**
+            * **Strengths:** [Concisely summarize the positive points from the Grammatical Range and Accuracy agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Grammatical Range and Accuracy agent's report.]
+            * **Expert Score:** [State the score given by the Grammatical Range and Accuracy agent.]
+
+            ---
+
+            **Final Analysis and Overall Score**
+            * **Summative Comments:** [Provide a brief (2-3 sentences) holistic overview. For example: "Overall, your report is logically structured, but its effectiveness is limited by an inaccurate Task Response, specifically the lack of a clear overview. Focusing on summarizing the main trends first will significantly boost your score."]
+            * **Overall Band Score:** [State the final, calculated, and correctly rounded overall score.]
+
+            Do not add any conversational closings, greetings, or encouragement to message again. Your response must end with the final Overall Band Score.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template(
+            """
+            Please generate a final Task 1 report based on the following four expert evaluations.
+
+            **TASK 1 TASK RESPONSE REPORT:**
+            ---
+            {task_response_report}
+            ---
+
+            **TASK 1 COHERENCE AND COHESION REPORT:**
+            ---
+            {coherence_cohesion_report}
+            ---
+
+            **TASK 1 LEXICAL RESOURCE REPORT:**
+            ---
+            {lexical_resource_report}
+            ---
+
+            **TASK 1 GRAMMATICAL RANGE AND ACCURACY REPORT:**
+            ---
+            {grammatical_range_and_accuracy_report}
+            ---
+            """
+        )
+    ])
+    
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "task_response_report": state["task_response"],
+        "coherence_cohesion_report": state["coherence_and_cohesion"],
+        "lexical_resource_report": state["lexical_resource"],
+        "grammatical_range_and_accuracy_report": state["grammatical_range_and_accuracy"]
+    })
+
+    logger.info("Final Report!")
+    return {"aggregated_result": response.content}
+

vendors/part1/state.py

@@ -0,0 +1,12 @@
+from typing import List, TypedDict, Union
+
+
+class State(TypedDict):
+    student_essay: str
+    image_url: str
+    task_response: str
+    coherence_and_cohesion: str
+    lexical_resource: str
+    grammatical_range_and_accuracy: str
+    estimated_band_score: float
+    aggregated_result: str

vendors/part1/workflow.py

@@ -0,0 +1,29 @@
+from langgraph.graph import StateGraph, START, END
+
+
+def workflow_fn(State, task_response, lexical_resource, grammatical_range_and_accuracy, coherence_and_cohesion, aggregator):
+    workflow = StateGraph(State)
+
+    workflow.add_node("Task Response", task_response)
+    workflow.add_node("Lexical", lexical_resource)
+    workflow.add_node("Grammar", grammatical_range_and_accuracy)
+    workflow.add_node("CC", coherence_and_cohesion)
+    workflow.add_node("Aggregator", aggregator)
+
+    workflow.add_edge(START, "Task Response")
+    workflow.add_edge(START, "Lexical")
+    workflow.add_edge(START, "Grammar")
+    workflow.add_edge(START, "CC")
+    workflow.add_edge("Task Response", "Aggregator")
+    workflow.add_edge("CC", "Aggregator")
+    workflow.add_edge("Grammar", "Aggregator")
+    workflow.add_edge("Lexical", "Aggregator")
+    workflow.add_edge("Aggregator", END)
+
+    workflow = workflow.compile()
+
+    with open("Workflow.md", "w") as f:
+        mermaid_code = workflow.get_graph().draw_mermaid()
+        f.write(f"```mermaid\n{mermaid_code}\n```")
+
+    return workflow

vendors/part2/Workflow.md

@@ -0,0 +1,28 @@
+```mermaid
+---
+config:
+  flowchart:
+    curve: linear
+---
+graph TD;
+	__start__([<p>__start__</p>]):::first
+	Task_Response(Task Response)
+	Lexical(Lexical)
+	Grammar(Grammar)
+	CC(CC)
+	Aggregator(Aggregator)
+	__end__([<p>__end__</p>]):::last
+	CC --> Aggregator;
+	Grammar --> Aggregator;
+	Lexical --> Aggregator;
+	Task_Response --> Aggregator;
+	__start__ --> CC;
+	__start__ --> Grammar;
+	__start__ --> Lexical;
+	__start__ --> Task_Response;
+	Aggregator --> __end__;
+	classDef default fill:#f2f0ff,line-height:1.2
+	classDef first fill-opacity:0
+	classDef last fill:#bfb6fc
+
+```

vendors/part2/display_report.py

@@ -0,0 +1,63 @@
+import json
+import re
+import textwrap
+
+
+class styles:
+    HEADER = '\033[95m'
+    GREEN = '\033[92m'
+    WARNING = '\033[93m'
+    BOLD = '\033[1m'
+    UNDERLINE = '\033[4m'
+    ENDC = '\033[0m'
+
+
+def print_md(text):
+    """
+    Translates simple markdown and wraps text for better terminal display.
+    """
+    text = re.sub(r'\*\*(.*?)\*\*', f'{styles.BOLD}\\1{styles.ENDC}', text)
+    paragraphs = text.split('\n')
+    wrapped_paragraphs = [textwrap.fill(p, width=90) for p in paragraphs]
+    final_text = '\n'.join(wrapped_paragraphs)
+    print(final_text)
+
+
+def display_report_fn(data):
+    """
+    Loads, parses, and prints the formatted IELTS report from a JSON file.
+    """
+
+    print("\n" + "=" * 80)
+    print(f"{styles.HEADER}{styles.BOLD}📝 IELTS WRITING EVALUATION REPORT{styles.ENDC}")
+    print("=" * 80)
+
+    if "original_question" in data:
+        print(f"\n{styles.HEADER}{styles.UNDERLINE}Original Question:{styles.ENDC}")
+        print_md(data["original_question"])
+
+    if "student_essay" in data:
+        print(f"\n{styles.HEADER}{styles.UNDERLINE}Student's Essay:{styles.ENDC}")
+        print_md(data["student_essay"])
+        print("-" * 80)
+
+    sections = {
+        "task_response": "✅ Task Response",
+        "coherence_and_cohesion": "🔗 Coherence and Cohesion",
+        "lexical_resource": "📚 Lexical Resource",
+        "grammatical_range_and_accuracy": "📝 Grammatical Range and Accuracy"
+    }
+
+    for key, title in sections.items():
+        if key in data:
+            print(f"\n\n{styles.GREEN}{styles.BOLD}{styles.UNDERLINE}--- {title} ---{styles.ENDC}\n")
+            print_md(data[key])
+
+    if "aggregated_result" in data:
+        print(
+            f"\n\n{styles.WARNING}{styles.BOLD}{styles.UNDERLINE}--- 📊 Overall Summary & Final Score ---{styles.ENDC}\n")
+        print_md(data["aggregated_result"])
+
+    print("\n" + "=" * 80 + "\n")
+
+

vendors/part2/final_state.json

@@ -0,0 +1,9 @@
+{
+    "student_essay": "One of the hot topics these day is about how the working week needs to be shorter and the need of longer weekends. However while I believe that people need to have enough time to rest after their working period, I don't think they need longer weekends to achieve that.\n\n\nFirstly, I think that there is plenty of time to rest after you get off from your work and prepare for the next day. Secondly, longer weekends will make people lazy and distant from their work. For example, when I was working at a tech company, we used to have 4 days off and when we would get back to work the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home. Thirdly, I read a recent study that discussed the impact of cutting working hours on the economy which showed massive damage to that country's economy in the long run.\n\n\nThere are several ways to improve your lifestyle while not having longer weekends. Most people tend to not plan their weekends at all and that can damage the quality of their time off. Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time. One of the best ways to make your job experience better is to find coworkers with the same interest as you. this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\n\n\nIn conclusion, I think while occasionally we need a time off from work to get into a better head space, there are other ways to tackle this problem without the need of cutting working days and making the weekends longer.",
+    "original_question": "The working week should be shorter and workers should have a longer weekend.\n\nDo you agree or disagree. ",
+    "task_response": "**1. What You Did Well:**\nYou successfully identified the core topic of the question and presented a clear and consistent position (disagreement) from the introduction through to the conclusion. You provided several relevant arguments to support your stance, such as the potential for laziness, the economic impact of reduced working hours, and the idea that current time off is sufficient if managed well. Your use of a personal anecdote to illustrate the point about becoming distant from work was a good attempt at providing specific support.\n\n**2. What You Could Have Done Better:**\nWhile your position was clear, some of your supporting points could have been more directly and strongly linked to the central argument against a shorter working week and longer weekend. For example, the point about finding coworkers with similar interests, while a valid way to improve job experience, doesn't directly argue against the *need* for a shorter working week or longer weekend in terms of rest or productivity. Its connection to the prompt's core argument was a bit indirect. Additionally, your reference to a \"recent study\" about economic impact, while a strong point, lacked specificity, which can weaken its persuasive power in terms of Task Response.\n\n**3. What You Missed:**\nYou did not completely miss any part of the prompt. You clearly addressed the \"agree or disagree\" aspect and provided reasons for your stance. The areas for improvement relate more to the depth and directness of the development of some ideas rather than an omission of a task component.\n\n**4. Recommendations for Improvement:**\n*   Before writing, ensure that every main idea and supporting example you plan to include directly and unequivocally supports your overall position. Ask yourself: \"How does this specific point or example directly prove why I agree or disagree with the prompt?\"\n*   When using external evidence or studies, try to be more specific if possible (e.g., \"Research from [institution] suggests...\") or frame it as a widely accepted concept if specific details are unavailable (e.g., \"It is widely understood that...\"). Avoid vague references like \"I read a recent study.\"\n*   Elaborate more fully on your main points. For instance, when you state there's \"plenty of time to rest,\" expand on *how* that time can be effectively utilized to achieve the desired rest, rather than just stating the fact.\n\n**5. Suggested Edits to Your Original Text:**\n\n*   **Your Original Sentence:** \"Firstly, I think that there is plenty of time to rest after you get off from your work and prepare for the next day.\"\n    *   **Higher-Scoring Alternative for Task Response:** \"Firstly, I contend that the current working structure already provides ample opportunity for rest and recuperation. Individuals can effectively manage their evenings and existing weekends to engage in leisure activities, pursue hobbies, and spend quality time with family, thereby mitigating the need for an extended break.\"\n\n*   **Your Original Sentence:** \"Thirdly, I read a recent study that discussed the impact of cutting working hours on the economy which showed massive damage to that country's economy in the long run.\"\n    *   **Higher-Scoring Alternative for Task Response:** \"Furthermore, a significant concern is the potential negative impact on national economies. Economic analyses often indicate that a reduction in working hours can lead to decreased productivity, higher operational costs for businesses, and ultimately, a decline in overall economic output, posing a long-term threat to prosperity.\"\n\n*   **Your Original Sentence:** \"One of the best ways to make your job experience better is to find coworkers with the same interest as you. this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\"\n    *   **Higher-Scoring Alternative for Task Response:** \"Beyond simply extending leisure time, improving job satisfaction itself can significantly enhance overall well-being, thereby reducing the perceived need for a shorter working week. For instance, fostering a positive work environment and encouraging social connections among colleagues can make the workday more enjoyable and less draining. My own experience, where forming friendships with colleagues who shared common interests like soccer transformed a challenging period into a more positive one, illustrates how internal workplace dynamics can be more impactful than simply increasing time away from work.\"\n\n**6. Final Task Response Score:** 7",
+    "coherence_and_cohesion": "**1. What You Did Well:**\nYour essay was clearly organized into an introduction, body paragraphs, and a conclusion, which provides a basic structure for your ideas. You also attempted to use linking words to introduce your points within the first body paragraph.\n\n**2. What You Could Have Done Better:**\nThe primary weakness in your essay's Coherence and Cohesion lies in the organization of your body paragraphs. Your first body paragraph is very long and contains three distinct arguments, which makes it difficult for the reader to follow a single, developed idea. The logical progression between your first and second body paragraphs is also not entirely smooth, as the second paragraph introduces a new line of argument (alternatives to longer weekends) rather than directly developing the reasons against them. Furthermore, your use of cohesive devices is somewhat mechanical and repetitive.\n\n**3. Cohesion and Coherence Breakdown:**\n*   **Paragraphing:** Your first body paragraph is a significant issue. It attempts to present three separate main ideas (\"plenty of time to rest,\" \"longer weekends make people lazy,\" and \"impact on economy\") within a single paragraph. For greater clarity and to allow for proper development of each point, these should have been separated into individual paragraphs. The second body paragraph also contains two distinct ideas (planning weekends and finding like-minded colleagues) that could benefit from clearer separation or more explicit linking.\n*   **Linking Words:** You rely heavily on \"Firstly,\" \"Secondly,\" and \"Thirdly\" to introduce points within one long paragraph. While these are cohesive devices, their repetitive use in this manner makes the writing feel mechanical rather than fluid. There is an underuse of a wider range of more sophisticated linking words and phrases that could show more complex relationships between sentences and paragraphs (e.g., cause and effect, contrast, further addition, exemplification). The transition from the first body paragraph to the second is abrupt, lacking a clear linking phrase to signal the shift in focus.\n*   **Referencing:** Referencing is generally clear (e.g., \"this\" referring to finding coworkers with the same interest). However, some phrasing like \"I was feeling distant with my job and felt the urge to be done with the work\" could be more concise to avoid slight repetition.\n\n**4. Recommendations for Improvement:**\n*   **Plan your paragraphs carefully:** Before you start writing, create a brief outline. Assign one central idea to each body paragraph. This will help you ensure that each paragraph has a clear topic sentence and develops a single argument thoroughly.\n*   **Vary your cohesive devices:** Expand your repertoire of linking words and phrases. Instead of just \"Secondly,\" consider using alternatives like \"Furthermore,\" \"Moreover,\" \"In addition to this,\" or \"Another significant point is that...\" to introduce new ideas. Use transition words to show the relationship between sentences (e.g., \"consequently,\" \"as a result,\" \"in contrast,\" \"however,\" \"for instance\").\n*   **Ensure logical progression between paragraphs:** Think about how each paragraph connects to the one before it and how it contributes to your overall argument. Use clear topic sentences and transitional phrases at the beginning of paragraphs to guide the reader smoothly from one idea to the next. For an \"agree/disagree\" essay, ensure your body paragraphs consistently support your stated stance.\n\n**5. Suggested Edits to Your Original Text:**\n\n*   **Original Body Paragraph 1:**\n    \"Firstly, I think that there is plenty of time to rest after you get off from your work and prepare for the next day. Secondly, longer weekends will make people lazy and distant from their work. For example, when I was working at a tech company, we used to have 4 days off and when we would get back to work the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home. Thirdly, I read a recent study that discussed the impact of cutting working hours on the economy which showed massive damage to that country's economy in the long run.\"\n\n*   **Higher-Scoring Alternative for Coherence and Cohesion (showing improved paragraphing and linking):**\n\n    \"To begin with, I believe that the current working week already provides sufficient time for individuals to rest and prepare for the following day. There is ample opportunity within the existing structure for personal rejuvenation without the need for extended weekends.\n\n    **Moreover,** a key concern is that longer weekends could inadvertently lead to a decline in productivity and a sense of detachment from one's profession. **For example,** during my experience at a tech company where we occasionally had four-day weekends, I observed that upon returning to work, both I and my colleagues often felt a diminished connection to our tasks, leading to a desire to complete work as quickly as possible rather than engaging deeply.\n\n    **Beyond individual impact,** there are significant economic considerations. I recently read a study that highlighted the substantial long-term damage inflicted upon a country's economy when working hours were significantly reduced, suggesting that such policies can have far-reaching negative consequences.\"\n\n*   **Original Body Paragraph 2:**\n    \"There are several ways to improve your lifestyle while not having longer weekends. Most people tend to not plan their weekends at all and that can damage the quality of their time off. Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time. One of the best ways to make your job experience better is to find coworkers with the same interest as you. this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\"\n\n*   **Higher-Scoring Alternative for Coherence and Cohesion (showing better linking and potential splitting):**\n\n    \"Instead of shortening the working week, there are alternative strategies to enhance one's lifestyle and well-being. **Crucially,** effective time management during existing weekends can significantly improve their quality. Many individuals fail to plan their time off, which often diminishes its restorative potential; conversely, thoughtful planning can lead to more fulfilling and productive leisure.\n\n    **Furthermore,** fostering positive social connections within the workplace can dramatically improve job satisfaction, thereby reducing the perceived need for longer breaks. This was certainly true in my own experience: after a challenging period at work, I connected with a colleague who shared my passion for soccer. Our discussions on various topics not only made the working environment more enjoyable but also fostered a stronger sense of belonging, making the work experience much more positive for both of us.\"\n\n**6. Final Coherence and Cohesion Score:** 5",
+    "lexical_resource": "**1. What You Did Well:**\nYou have used some basic topic-specific vocabulary related to work and leisure, such as 'working week', 'weekends', 'time off', and 'economy'. You also attempted to use some phrases to express your opinion, like 'I believe that' and 'I don't think'.\n\n**2. What You Could Have Done Better:**\nThe essay relies heavily on a limited range of vocabulary, leading to repetition and a lack of precision. Many phrases are informal or colloquial, which is not appropriate for an academic essay. There is a consistent lack of sophisticated vocabulary and an absence of less common lexical items. Word choice and collocations are frequently unnatural, making the text sound less fluent and professional.\n\n**3. Lexical Resource Breakdown:**\n\n*   **Repetition:**\n    *   The word \"work/working\" is used excessively (e.g., \"working week,\" \"working period,\" \"get off from your work,\" \"back to work,\" \"my job,\" \"the work,\" \"working hours,\" \"at work,\" \"working experience,\" \"from work,\" \"working days\").\n    *   \"Time\" is repeated frequently (e.g., \"enough time,\" \"plenty of time,\" \"time off,\" \"quality time\").\n    *   \"Better\" is overused (e.g., \"better use,\" \"make your job experience better,\" \"better for both of us,\" \"better head space\").\n    *   \"Need\" is repeated (e.g., \"needs to be shorter,\" \"need of longer weekends,\" \"people need to have,\" \"we need a time off,\" \"without the need of cutting\").\n    *   \"Feel/feeling\" is repeated in the same sentence: \"didn't feel the same as I was feeling distant.\"\n\n*   **Word Choice/Collocation:**\n    *   \"hot topics these day\" - \"these days\" is correct, but \"hot topics\" is informal. Consider \"a widely debated issue\" or \"a prominent discussion point.\"\n    *   \"the need of longer weekends\" - Should be \"the need *for* longer weekends.\"\n    *   \"get off from your work\" - More natural would be \"finish work\" or \"leave work.\"\n    *   \"make people lazy and distant from their work\" - \"Foster laziness and detachment from their professional responsibilities\" would be more precise. \"Distant from their work\" is awkward.\n    *   \"the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job\" - Very repetitive and unnatural. Consider \"I felt a diminished connection to my role and colleagues, experiencing a sense of detachment.\"\n    *   \"felt the urge to be done with the work as quickly as possible\" - \"Felt compelled to complete tasks swiftly.\"\n    *   \"massive damage to that country's economy\" - \"Massive damage\" is informal. Use \"significant detriment\" or \"severe adverse impact.\"\n    *   \"improve your lifestyle while not having longer weekends\" - \"Enhance one's lifestyle without necessarily extending weekends.\"\n    *   \"damage the quality of their time off\" - \"Detract from the quality of their leisure time.\"\n    *   \"Good planning will guide you to find better use of you quality time\" - \"Effective planning can enable individuals to make better use of their leisure time.\" (\"you quality time\" is a grammatical error, should be \"your\").\n    *   \"make your job experience better\" - \"Enhance one's professional experience.\"\n    *   \"having a rough few weeks at work\" - \"Rough\" is informal. Consider \"experiencing a challenging period at work.\"\n    *   \"discuss about our opinion\" - \"Discuss our opinion\" (no \"about\").\n    *   \"get into a better head space\" - \"Head space\" is informal. Consider \"achieve a more positive mental state\" or \"improve one's well-being.\"\n    *   \"tackle this problem\" - \"Address this issue\" or \"resolve this challenge.\"\n\n*   **Spelling/Word Formation:**\n    *   \"these day\" (should be \"these days\")\n    *   \"you quality time\" (should be \"your quality time\")\n\n**4. Recommendations for Improvement:**\n*   **Expand your vocabulary range:** Actively learn synonyms and antonyms for common words. For example, instead of just \"good\" or \"bad,\" learn \"beneficial,\" \"detrimental,\" \"advantageous,\" \"adverse,\" etc.\n*   **Focus on precision:** Choose words that convey your meaning exactly. For instance, instead of \"big problem,\" use \"significant issue\" or \"major challenge.\"\n*   **Improve collocation awareness:** Pay attention to how words naturally go together. Use a collocation dictionary or notice common phrases in authentic English texts. For example, \"make a decision,\" not \"do a decision.\"\n*   **Elevate your style:** Avoid informal language and colloquialisms in academic writing. Replace phrases like \"get off from your work\" or \"rough few weeks\" with more formal alternatives.\n*   **Practice paraphrasing:** When you write, try to rephrase ideas using different vocabulary to avoid repetition.\n\n**5. Suggested Edits to Your Original Text:**\n\n*   *Your Original Text:* \"One of the hot topics these day is about how the working week needs to be shorter and the need of longer weekends.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"**A prominent discussion point** currently revolves around the **proposal for a shorter working week** and the **extension of weekends**.\"\n\n*   *Your Original Text:* \"I think that there is plenty of time to rest after you get off from your work and prepare for the next day.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"I believe that individuals have **ample opportunity for recuperation** after **concluding their workdays** to prepare for the subsequent one.\"\n\n*   *Your Original Text:* \"longer weekends will make people lazy and distant from their work.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"Extended weekends could **foster indolence** and **detachment from one's professional responsibilities**.\"\n\n*   *Your Original Text:* \"the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"I experienced a **diminished connection** to my role and colleagues, feeling **disengaged** and **compelled to complete tasks swiftly** in order to return home.\"\n\n*   *Your Original Text:* \"cutting working hours on the economy which showed massive damage to that country's economy in the long run.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"reducing working hours on the economy, which indicated **significant detriment** to that nation's economy in the long run.\"\n\n*   *Your Original Text:* \"Most people tend to not plan their weekends at all and that can damage the quality of their time off. Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"Many individuals often **neglect to plan their weekends effectively**, which can **detract from the quality of their leisure time**. **Strategic planning** can enable them to **optimise their free time** and establish achievable goals within a defined period.\"\n\n*   *Your Original Text:* \"occasionally we need a time off from work to get into a better head space, there are other ways to tackle this problem without the need of cutting working days and making the weekends longer.\"\n    *   *Higher-Scoring Alternative for Lexical Resource:* \"while occasional **breaks from work** are necessary to **achieve a more positive mental state**, alternative strategies exist to **address this issue** without the necessity of reducing working days or extending weekends.\"\n\n**6. Final Lexical Resource Score:** 5",
+    "grammatical_range_and_accuracy": "**1. What You Did Well:**\nYou have demonstrated a good attempt at using a mix of simple, compound, and complex sentence structures. There is clear evidence of complex sentences, particularly those using subordinate clauses (e.g., \"while I believe that...\", \"when I was working...\") and relative clauses (e.g., \"that discussed...\", \"who also loved...\"). This shows a good range in your grammatical structures. You also successfully use introductory phrases and clauses, often followed by correct punctuation.\n\n**2. What You Could Have Done Better:**\nWhile you attempt complex structures, there are frequent grammatical errors that, though often minor, accumulate and affect overall accuracy. These errors include issues with articles, prepositions, singular/plural forms, and occasional tense inconsistencies. Some very long sentences become slightly unwieldy, indicating a need for more precise control over highly complex constructions and better punctuation to manage their flow.\n\n**3. Grammatical Range and Accuracy Breakdown:**\n*   **Sentence Structure:** You effectively use a variety of sentence types, moving beyond simple sentences to incorporate complex ones. This includes sentences with noun clauses (\"how the working week needs to be shorter\"), adverbial clauses of time and concession (\"when I was working...\", \"while I believe...\"), and relative clauses (\"that discussed...\", \"who also loved...\"). This demonstrates a good range. However, some sentences are excessively long, which can lead to awkward phrasing and a slight loss of clarity, suggesting that while you attempt complex structures, full control over their most intricate forms is still developing.\n*   **Grammatical Errors:**\n    *   **Articles:** You sometimes omit or misuse articles, for example, \"a time off\" should be \"time off.\"\n    *   **Prepositions:** There are recurring errors with prepositions, such as \"the need of longer weekends\" (should be \"the need for\"), \"get off from your work\" (should be \"get off work\"), \"distant with my job\" (should be \"distant from my job\"), and \"discuss about our opinion\" (should be \"discuss our opinion\").\n    *   **Singular/Plural:** You used \"these day\" instead of \"these days\" and \"our opinion on different topics\" instead of \"our opinions on different topics.\"\n    *   **Tense Consistency:** In the sentence \"so I can go back home,\" the present tense \"can\" is inconsistent with the past context of the narrative (\"when I was working...\"). It should be \"so that I could go back home.\"\n    *   **Word Choice/Phrasing:** Phrases like \"tend to not plan\" could be more naturally expressed as \"tend not to plan.\" \"use of you quality time\" should be \"use of your quality time.\"\n*   **Punctuation:**\n    *   You occasionally miss commas after introductory clauses (e.g., \"However while I believe...\" should be \"However, while I believe...\").\n    *   There is a significant run-on sentence due to a lack of capitalization and appropriate punctuation: \"this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\" This sentence is too long and should be broken up or use a semicolon.\n\n**4. Recommendations for Improvement:**\n*   **Focus on Prepositions and Articles:** Dedicate specific practice to common prepositional phrases and the rules for using 'a,' 'an,' and 'the,' especially with abstract nouns or general statements.\n*   **Review Singular/Plural Nouns:** Pay close attention to whether nouns should be singular or plural, particularly when referring to general concepts or multiple items.\n*   **Master Complex Sentence Punctuation:** Practice using commas correctly with dependent and independent clauses. Learn how to use semicolons to connect closely related independent clauses, or how to split very long sentences into two or more shorter, clearer ones.\n*   **Ensure Tense Consistency:** When narrating events or discussing past experiences, ensure that all verbs maintain a consistent tense unless there's a specific reason for a shift.\n*   **Proofread Systematically:** After writing, review your essay specifically for one type of grammatical error at a time (e.g., first check all prepositions, then all articles, then all subject-verb agreements).\n\n**5. Suggested Edits to Your Original Text:**\n*   **Your Original Text:** \"One of the hot topics these day is about how the working week needs to be shorter and the need of longer weekends.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"One of the hot topics these **days** is **the debate about** how the working week needs to be shorter and the need **for** longer weekends.\"\n*   **Your Original Text:** \"However while I believe that people need to have enough time to rest after their working period, I don't think they need longer weekends to achieve that.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"However, while I believe that people need to have enough time to rest after their working period, I don't think they need longer weekends to achieve that.\"\n*   **Your Original Text:** \"For example, when I was working at a tech company, we used to have 4 days off and when we would get back to work the connection I had with my job and colleagues didn't feel the same as I was feeling distant with my job and felt the urge to be done with the work as quickly as possible so I can go back home.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"For example, when I was working at a tech company, we used to have four days off. When we returned to work, the connection I had with my job and colleagues didn't feel the same; I felt distant from my job and had the urge to finish work as quickly as possible so that I could go back home.\"\n*   **Your Original Text:** \"Good planning will guide you to find better use of you quality time and setting the goals you want to achieve by a certain time.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"Good planning will guide you to make better use of **your** quality time and to set the goals you want to achieve by a certain time.\"\n*   **Your Original Text:** \"this was the case for me as I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did and we used to discuss about our opinion on different topics which made the working experience much better for both of us.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"**This** was the case for me: I was having a rough few weeks at work but then ended up meeting one of my best friends who also loved soccer as much as I did. We used to discuss our **opinions** on different topics, which made the working experience much better for both of us.\"\n*   **Your Original Text:** \"In conclusion, I think while occasionally we need a time off from work to get into a better head space, there are other ways to tackle this problem without the need of cutting working days and making the weekends longer.\"\n    *   **Higher-Scoring Alternative for Grammatical Range and Accuracy:** \"In conclusion, I think while occasionally we need time off from work to get into a better headspace, there are other ways to tackle this problem without the need **for** cutting working days and making the weekends longer.\"\n\n**6. Final Grammatical Range and Accuracy Score:**\n6",
+    "aggregated_result": "**Overall IELTS Writing Task 2 Feedback**\n\nHere is a summary of your performance based on the four official IELTS scoring criteria.\n\n**1. Task Response**\n*   **Strengths:** You clearly identified the core topic and maintained a consistent position of disagreement throughout the essay. You provided several relevant arguments, such as the potential for laziness, economic impact, and the sufficiency of current time off. The attempt to use a personal anecdote for illustration was also noted.\n*   **Areas for Improvement:** Some supporting points could have been more directly linked to the central argument against a shorter working week. The connection of finding similar-interest coworkers to the prompt's core argument was indirect. Additionally, the reference to a \"recent study\" lacked specificity, which weakened its persuasive power.\n*   **Expert Score:** 7\n\n**2. Coherence and Cohesion**\n*   **Strengths:** Your essay demonstrated a clear basic structure with an introduction, body paragraphs, and a conclusion. You also attempted to use linking words to introduce points within the first body paragraph.\n*   **Areas for Improvement:** The primary weakness was the organization of body paragraphs, particularly the first, which was excessively long and contained three distinct arguments. The logical progression between the first and second body paragraphs was not smooth, and the use of cohesive devices was somewhat mechanical and repetitive.\n*   **Expert Score:** 5\n\n**3. Lexical Resource (Vocabulary)**\n*   **Strengths:** You used some basic topic-specific vocabulary related to work and leisure. You also attempted to use phrases to express your opinion.\n*   **Areas for Improvement:** The essay relied on a limited vocabulary range, leading to repetition and a lack of precision. Many phrases were informal or colloquial, which is not appropriate for academic writing. There was a consistent absence of sophisticated vocabulary and less common lexical items, and word choice and collocations were frequently unnatural.\n*   **Expert Score:** 5\n\n**4. Grammatical Range and Accuracy**\n*   **Strengths:** You demonstrated a good attempt at using a mix of simple, compound, and complex sentence structures, including subordinate and relative clauses. You also successfully used introductory phrases and clauses, often with correct punctuation.\n*   **Areas for Improvement:** Despite attempts at complex structures, frequent grammatical errors accumulated, affecting overall accuracy. These included issues with articles, prepositions, singular/plural forms, and occasional tense inconsistencies. Some very long sentences became unwieldy, indicating a need for more precise control over complex constructions and better punctuation.\n*   **Expert Score:** 6\n\n---\n\n**Final Analysis and Overall Score**\n*   **Summative Comments:** Overall, your ability to present a clear position and attempt a range of sentence structures are notable strengths. However, your final score is primarily limited by issues in Coherence and Cohesion, particularly paragraphing, and a restricted range of vocabulary with frequent errors in word choice and collocation. Grammatical accuracy, especially with prepositions and articles, also requires attention.\n*   **Overall Band Score:** 6.0"
+}

vendors/part2/main.py

@@ -0,0 +1,49 @@
+from langgraph.graph import StateGraph, START, END
+from typing_extensions import Literal
+from langchain_core.messages import HumanMessage, SystemMessage
+import io
+import sys
+
+from .nodes import task_response, coherence_and_cohesion, lexical_resource, grammatical_range_and_accuracy, aggregator
+from .state import State
+from .workflow import workflow_fn
+from .display_report import display_report_fn
+
+
+def run_ielts_part2_agent(original_question: str, student_essay: str) -> str:
+    """
+    Runs the IELTS Part 2 agent and captures the output report as a string.
+    """
+    initial_state = {
+        "original_question": original_question,
+        "student_essay": student_essay
+    }
+
+    # Initialize the LangGraph workflow
+    final_workflow = workflow_fn(State, task_response, lexical_resource, grammatical_range_and_accuracy,
+                                 coherence_and_cohesion, aggregator)
+
+    # Invoke the agent with the initial state
+    final_state = final_workflow.invoke(initial_state)
+
+    # --- Capture the printed output of display_report_fn ---
+    old_stdout = sys.stdout
+    sys.stdout = captured_output = io.StringIO()
+
+    display_report_fn(final_state)  # This function now prints into our captured_output
+
+    sys.stdout = old_stdout  # Restore standard output
+    report_string = captured_output.getvalue()  # Get the string from the buffer
+
+    return report_string
+
+
+# This part is for your own direct testing of the script
+if __name__ == "__main__":
+    test_question = "Some people believe that unpaid community service should be a compulsory part of high school programmes. To what extent do you agree or disagree?"
+    test_essay = "Community service is a noble act. I believe it should be mandatory for all high school students..."
+
+    print("--- Running test for Part 2 ---")
+    result = run_ielts_part2_agent(test_question, test_essay)
+    print("\n--- Agent Result ---")
+    print(result)

vendors/part2/model.py

@@ -0,0 +1,5 @@
+from langchain_google_genai import ChatGoogleGenerativeAI
+from dotenv import load_dotenv
+
+load_dotenv()
+model = ChatGoogleGenerativeAI(model='gemini-2.5-flash-preview-05-20', temperature=0.1, top_p=0.95)

vendors/part2/nodes.py

@@ -0,0 +1,434 @@
+from .state import State
+from langchain_core.prompts import ChatPromptTemplate, SystemMessagePromptTemplate, HumanMessagePromptTemplate
+from .model import model
+import logging
+
+logger = logging.getLogger(__name__)
+
+def task_response(state: State):
+    print("--Starting Task Response Analysis--")
+    logger.info("Starting Task Response Analysis")
+
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner. Your sole function is to assess a student's Writing Task 2 response based *only* on the **Task Response** criterion. You will be given a question and a student's essay. You must ignore all other scoring criteria, including Coherence and Cohesion, Lexical Resource, and Grammatical Range and Accuracy. Your analysis must be exclusively focused on how well the student has addressed the prompt.
+
+            **Your Role and How to Score Task Response:**
+
+            Your primary job is to evaluate whether the student has fully and appropriately addressed all parts of the task. To do this, you will meticulously analyze the provided essay against the official IELTS Task Response descriptors.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Deconstruct the Prompt:** First, break down the question into its core components. Does it ask for an opinion? To discuss two views? To outline problems and solutions? To answer two direct questions? Identify every single part that requires a response.
+            2.  **Assess the Introduction:** Does the introduction paraphrase the question effectively and, most importantly, present a clear thesis statement that directly answers the question and outlines the essay's position?
+            3.  **Evaluate Body Paragraphs:**
+                * Does each body paragraph address a specific part of the prompt?
+                * Are the main ideas in each paragraph relevant to the question? Or do they drift off-topic?
+                * Is the position presented throughout the essay clear and consistent?
+                * Are the ideas supported with relevant, specific examples, reasons, and evidence? Or are they vague, over-generalized, or unsupported?
+            4.  **Check the Conclusion:** Does the conclusion summarize the main points and restate the position in a clear way, directly linking back to the question?
+            5.  **Identify Misinterpretations:** Did the student misunderstand any part of the question? Did they address the topic in a general sense but miss the specific nuance of the prompt?
+
+            **Task Response Scoring Guide (Strictly follow this):**
+            * **Band 8:** The response fully addresses all parts of the question with a well-developed and relevant position. Ideas are extended and supported with specific evidence.
+            * **Band 7:** The response addresses all parts of the question, though some parts may be more fully covered than others. The position is clear throughout, and main ideas are extended and supported, but there might be a tendency to over-generalize at times.
+            * **Band 6:** The response addresses the prompt, but the treatment of the topic may be more general. The position is relevant but conclusions may be unclear or repetitive. Main ideas are present but may not be sufficiently developed or supported with specific examples.
+            * **Band 5:** The response addresses the task only partially; the format may be inappropriate. The position is unclear, and ideas are limited, not well-developed, or irrelevant.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+            Start with positive reinforcement. Briefly mention aspects of the Task Response that were handled correctly. For example, "You successfully identified the general topic of the question and presented some relevant ideas."
+
+            **2. What You Could Have Done Better:**
+            Provide a detailed critique of the weaknesses in the Task Response. Be specific. For example, "While you discussed the advantages of the topic, you did not adequately address the second part of the question which asked for the disadvantages." or "Your position was not made clear until the conclusion, it should be presented in the introduction."
+
+            **3. What You Missed:**
+            Clearly state any parts of the prompt that were completely ignored or significantly misunderstood. For example, "The prompt asked you to discuss both views and give your own opinion. Your essay only focused on one view and did not state your personal opinion clearly."
+
+            **4. Recommendations for Improvement:**
+            Give actionable advice on how the student can improve their Task Response skills for future essays. This should be general advice based on the mistakes identified. For instance, "Always break down the question into micro-questions before you start writing to ensure you cover every part. For each main idea you present, ask yourself 'Why?' or 'How?' and answer it with a specific example."
+
+            **5. Suggested Edits to Your Original Text:**
+            This is a crucial section. Provide specific, revised sentences or short paragraphs that show the student *exactly* how they could have phrased parts of their original essay to score higher in Task Response. You should directly quote a small part of their text and then provide a "Higher-Scoring Alternative".
+            *Example:*
+            *Your Original Sentence:* "Some people think technology is good for society."
+            *Higher-Scoring Alternative for Task Response:* "While the proliferation of technology has undoubtedly brought convenience, a significant viewpoint is that its detrimental effects on social interaction and mental well-being are far more pronounced." (This directly addresses a "discuss both views" prompt).
+
+            **6. Final Task Response Score:**
+            Conclude with the final band score for Task Response only. No further comments.
+            *Example:*
+            "Final Task Response Score: 6"
+
+            Do not add any conversational closings, greetings, or encouragement to message again. Your response must end with the final score.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template(
+            """
+            **IELTS Writing Task 2 Question:**
+            {question}
+
+            **Student's Response:**
+            {student_response}
+            """
+        )
+    ])
+
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "question": state["original_question"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"task_response": response.content}
+
+
+def coherence_and_cohesion(state: State):
+    print("--Starting CC Analysis--")
+    logger.info("Starting CC Analysis")
+
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner. Your sole function is to assess a student's Writing Task 2 response based *only* on the **Coherence and Cohesion** criterion. You will be given a question and a student's essay. You must ignore all other scoring criteria, including Task Response, Lexical Resource, and Grammatical Range and Accuracy. Your analysis must be exclusively focused on the organization, flow, and linking of ideas within the essay.
+
+            **Your Role and How to Score Coherence and Cohesion:**
+
+            Your primary job is to evaluate how the essay is organized and how the ideas are linked. Coherence refers to the logical sequencing of ideas, while Cohesion refers to the grammatical and lexical linking within and between sentences.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Overall Structure:** Does the essay have a clear and logical structure, including an introduction, distinct body paragraphs, and a conclusion?
+            2.  **Paragraphing:** Is the paragraphing logical and effective? Does each paragraph have a clear central topic? Are there paragraphs that are too long or too short (e.g., one-sentence paragraphs)?
+            3.  **Progression:** Is there a clear and logical progression of ideas throughout the essay? Can you easily follow the writer's line of thought from one point to the next, or does it jump around?
+            4.  **Topic Sentences:** Does each body paragraph begin with a clear topic sentence that introduces the main idea of that paragraph?
+            5.  **Cohesive Devices:**
+                * **Range and Accuracy:** Does the student use a range of linking words and phrases (e.g., 'Furthermore', 'In contrast', 'As a result', 'For instance')? Are these devices used accurately and naturally, or are they mechanical, repetitive, or incorrect?
+                * **Overuse/Underuse:** Is there an overuse of simple linkers (like 'and', 'but', 'so') or an underuse of any cohesive devices, making the text difficult to follow?
+            6.  **Referencing:** Is referencing (e.g., using pronouns like 'it', 'they', 'this', 'these') clear and unambiguous? Is it easy to tell what the pronouns refer to?
+
+            **Coherence and Cohesion Scoring Guide (Strictly follow this):**
+            * **Band 8:** The essay is skillfully managed. It features logical paragraphing with clear progression throughout. A wide range of cohesive devices is used appropriately and flexibly.
+            * **Band 7:** The essay is logically organized and there is a clear progression throughout. A range of cohesive devices is used effectively, but there may be some under- or over-use. Paragraphing is generally logical.
+            * **Band 6:** The essay is organized, and there is a mostly clear overall progression. Cohesive devices are used, but they may be faulty, mechanical, or repetitive. Paragraphing may not always be logical.
+            * **Band 5:** There is some organization, but it's not always logical and lacks overall progression. Cohesive devices may be inadequate, inaccurate, or overused. Paragraphing may be missing or inadequate.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+            Start with positive reinforcement on the structure. For example, "Your essay was clearly organized into an introduction, body, and conclusion, which provides a basic structure for your ideas."
+
+            **2. What You Could Have Done Better:**
+            Provide a detailed critique of the weaknesses in Coherence and Cohesion. Be specific. For example, "The connection between your second and third body paragraphs was unclear, as there was no transition to signal a shift in argument." or "You have overused the linking word 'Also' to begin sentences, which makes the essay feel repetitive."
+
+            **3. Cohesion and Coherence Breakdown:**
+            Give a more structured analysis of specific issues.
+            * **Paragraphing:** Comment on the effectiveness of the paragraph structure. Example: "Your second paragraph contained two separate ideas that should have been split into two paragraphs for greater clarity."
+            * **Linking Words:** Comment on the use of cohesive devices. Example: "The use of 'In addition' in the third paragraph was inaccurate because the idea presented was a contrast, not an addition. 'In contrast' would have been more appropriate."
+            * **Referencing:** Comment on the use of pronouns. Example: "In the sentence 'They believe this is a problem,' the pronoun 'this' is unclear. It is not immediately obvious what problem you are referring to from the previous sentence."
+
+            **4. Recommendations for Improvement:**
+            Give actionable advice on how to improve. For instance, "Before writing, create an outline where you assign one central idea to each paragraph. Then, think about how that idea connects to the next and choose a specific transition word or phrase to signal that relationship to the reader."
+
+            **5. Suggested Edits to Your Original Text:**
+            Provide specific, revised sentences or short passages that show the student *exactly* how they could have improved the flow and connection in their essay.
+            *Example:*
+            *Your Original Text:* "Fast food is unhealthy. It is very popular. People are getting more obese."
+            *Higher-Scoring Alternative for Coherence and Cohesion:* "Despite its undeniable popularity, fast food is notoriously unhealthy. **As a direct consequence of its widespread consumption,** obesity rates have seen a dramatic increase in recent years." (This uses a cohesive phrase to clearly link the cause and effect).
+
+            **6. Final Coherence and Cohesion Score:**
+            Conclude with the final band score for Coherence and Cohesion only. No further comments.
+            *Example:*
+            "Final Coherence and Cohesion Score: 5"
+
+            Do not add any conversational closings, greetings, or encouragement to message again. Your response must end with the final score.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template(
+            """
+            **IELTS Writing Task 2 Question:**
+            {question}
+
+            **Student's Response:**
+            {student_response}
+            """
+        )
+    ])
+    
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "question": state["original_question"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"coherence_and_cohesion": response.content}
+
+
+def lexical_resource(state: State):
+    print("--Starting Lexical Resource Analysis--")
+    logger.info("Starting Lexical Resource Analysis")
+
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner. Your sole function is to assess a student's Writing Task 2 response based *only* on the **Lexical Resource** criterion. This means you will evaluate the range, accuracy, and appropriacy of the vocabulary used. You must ignore all other scoring criteria, including Task Response, Coherence and Cohesion, and Grammatical Range and Accuracy.
+
+            **Your Role and How to Score Lexical Resource:**
+
+            Your primary job is to evaluate the writer's vocabulary. This isn't just about using "difficult" words; it's about using a wide range of vocabulary accurately and effectively to convey precise meaning.
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Range of Vocabulary:** Does the writer use a wide range of words and phrases, or do they rely on a small set of common words? Is there evidence of less common vocabulary?
+            2.  **Repetition:** Does the writer repeat the same words and phrases from the prompt or from their own writing?
+            3.  **Precision and Appropriacy:** Are words used accurately and in the correct context? Does the writer choose the best word to express their meaning, or is the meaning sometimes unclear due to poor word choice?
+            4.  **Collocations:** Does the writer show an awareness of how words naturally go together (e.g., 'express concern,' not 'say concern'; 'a major factor,' not 'a big factor')?
+            5.  **Word Formation and Spelling:** Are there errors in word formation (e.g., using 'economic' instead of 'economy') or spelling? How much do these errors interfere with communication?
+            6.  **Style and Tone:** Is the vocabulary appropriate for a formal essay? Or is it too informal or conversational?
+
+            **Lexical Resource Scoring Guide (Strictly follow this):**
+            * **Band 8:** Shows a wide range of vocabulary with skill and precision. Uses less common and idiomatic vocabulary skillfully. Produces rare errors in spelling or word formation.
+            * **Band 7:** Uses a sufficient range of vocabulary to allow for some flexibility and precision. Uses some less common lexical items with an awareness of style and collocation. May produce occasional errors in word choice, spelling, or word formation.
+            * **Band 6:** Uses an adequate range of vocabulary for the task. Attempts to use less common vocabulary but with some inaccuracy. Makes some errors in spelling and/or word formation, but they do not impede communication.
+            * **Band 5:** Uses a limited range of vocabulary, but it is minimally adequate for the task. Makes noticeable errors in spelling and/or word formation that may cause some difficulty for the reader.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+            Start with positive reinforcement on vocabulary usage. For example, "You have used some topic-specific vocabulary correctly, such as 'environmental pollution' and 'industrial waste'."
+
+            **2. What You Could Have Done Better:**
+            Provide a detailed critique of the weaknesses in Lexical Resource. Be specific. For example, "The essay relied heavily on repeating the words 'good' and 'bad' to express your opinion. Using more precise adjectives like 'beneficial,' 'advantageous,' 'detrimental,' or 'harmful' would have shown a wider range."
+
+            **3. Lexical Resource Breakdown:**
+            Give a more structured analysis of specific issues.
+            * **Repetition:** List words that were overused. Example: "The word 'student' was used 12 times. You could have used synonyms like 'learners,' 'pupils,' or 'young people'."
+            * **Word Choice/Collocation:** Point out specific instances of incorrect or unnatural word use. Example: "The phrase 'make a solution' is an incorrect collocation. The correct phrase is 'find a solution' or 'propose a solution'."
+            * **Spelling/Word Formation:** Note any errors. Example: "There was a spelling error in 'goverment' (correct: 'government') and an error in word formation with 'successfull' (correct: 'successful')."
+
+            **4. Recommendations for Improvement:**
+            Give actionable advice. For instance, "When you learn a new word, also learn its synonyms, antonyms, and common collocations. Actively try to replace simple words like 'important' or 'get' with more precise alternatives like 'crucial,' 'essential,' 'acquire,' or 'obtain' in your practice essays."
+
+            **5. Suggested Edits to Your Original Text:**
+            Provide specific, revised sentences that show the student *exactly* how they could have used better vocabulary.
+            *Example:*
+            *Your Original Text:* "This is a big problem because a lot of people get sick."
+            *Higher-Scoring Alternative for Lexical Resource:* "**This is a significant issue** because **a considerable portion of the population** **suffers from** various ailments as a result."
+
+            **6. Final Lexical Resource Score:**
+            Conclude with the final band score for Lexical Resource only. No further comments.
+            *Example:*
+            "Final Lexical Resource Score: 6"
+
+            Do not add any conversational closings, greetings, or encouragement to message again. Your response must end with the final score.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template(
+            """
+            **IELTS Writing Task 2 Question:**
+            {question}
+
+            **Student's Response:**
+            {student_response}
+            """
+        )
+    ])
+    
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "question": state["original_question"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"lexical_resource": response.content}
+
+
+def grammatical_range_and_accuracy(state: State):
+    print("--Starting Grammar Analysis--")
+    logger.info("Starting Grammar Analysis")
+
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are an expert IELTS Writing Examiner. Your sole function is to assess a student's Writing Task 2 response based *only* on the **Grammatical Range and Accuracy (GRA)** criterion. You will evaluate the variety, complexity, and correctness of the grammatical structures used. You must ignore all other scoring criteria, including Task Response, Coherence and Cohesion, and Lexical Resource.
+
+            **Your Role and How to Score Grammatical Range and Accuracy:**
+
+            Your primary job is to analyze the writer's control and use of grammar. This involves assessing both the variety of sentence structures (range) and the number and severity of errors (accuracy).
+
+            **What to Look For (Your Internal Checklist):**
+            1.  **Sentence Structures:**
+                * **Range:** Does the writer use a mix of simple, compound, and complex sentences? Or is the writing dominated by simple sentences?
+                * **Complex Sentences:** Is there evidence of complex structures, such as sentences with subordinate clauses (e.g., using 'while', 'although', 'which', 'if'), conditional sentences, or passive voice?
+            2.  **Grammatical Accuracy:**
+                * **Error Frequency:** How frequent are grammatical errors? Are they systematic (the same error repeated) or random?
+                * **Error Impact:** Do the errors impede communication and make the text difficult to understand? Or are they minor slips that don't cause confusion?
+                * **Error Types:** Identify the types of errors, such as subject-verb agreement, tense usage, articles (a/an/the), prepositions, word order, and run-on sentences or sentence fragments.
+            3.  **Punctuation:** Is punctuation (commas, periods, apostrophes) used correctly? Are there errors like comma splices or a lack of commas where needed, which affect readability?
+
+            **Grammatical Range and Accuracy Scoring Guide (Strictly follow this):**
+            * **Band 8:** Uses a wide range of structures with flexibility and accuracy. The vast majority of sentences are error-free, with only very rare, non-systematic errors or inappropriacies.
+            * **Band 7:** Uses a variety of complex structures. Produces frequent error-free sentences. Has good control of grammar and punctuation, but may make a few errors.
+            * **Band 6:** Uses a mix of simple and complex sentence forms. Makes some errors in grammar and punctuation, but they rarely reduce communication.
+            * **Band 5:** Uses only a limited range of structures. Attempts complex sentences, but these tend to be less accurate than simple sentences. Makes frequent grammatical errors, and punctuation may be faulty; errors can cause some difficulty for the reader.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a response in the following order and with these exact headings:
+
+            **1. What You Did Well:**
+            Start with positive reinforcement on grammar. For example, "You have demonstrated correct use of the simple present tense and constructed several error-free simple sentences."
+
+            **2. What You Could Have Done Better:**
+            Provide a detailed critique of the weaknesses in GRA. Be specific. For example, "The essay relied heavily on simple and compound sentences, with very few complex structures. This limits the grammatical range. Furthermore, there were consistent errors with subject-verb agreement."
+
+            **3. Grammatical Range and Accuracy Breakdown:**
+            Give a more structured analysis of specific issues.
+            * **Sentence Structure:** Comment on the variety of sentences used. Example: "Over 80% of your sentences were simple sentences. To improve your range, you should try to combine some of these ideas using subordinating conjunctions like 'although' or 'because'."
+            * **Grammatical Errors:** List the types of repeated errors. Example: "There were several errors with articles, such as 'government should help the poor people' instead of '...help poor people'. Another common error was incorrect tense usage, for instance, 'Yesterday, he go to school'."
+            * **Punctuation:** Note any punctuation errors. Example: "You have a comma splice in the sentence 'The government implemented the policy, it was not successful.' This should be a period or a semicolon."
+
+            **4. Recommendations for Improvement:**
+            Give actionable advice. For instance, "Focus on learning to write sentences with relative clauses (using 'who,' 'which,' 'that'). After writing a practice essay, review it specifically for one type of error, such as subject-verb agreement, until you become more comfortable with the rule."
+
+            **5. Suggested Edits to Your Original Text:**
+            Provide specific, revised sentences that show the student *exactly* how they could have used better grammar or sentence structure.
+            *Example:*
+            *Your Original Text:* "The internet is useful. It helps people to connect. Some people use it too much."
+            *Higher-Scoring Alternative for Grammatical Range and Accuracy:* "**Although the internet is a useful tool that helps people to connect,** there is a growing concern that some individuals use it excessively." (This combines three simple sentences into one complex sentence, showing greater grammatical control).
+
+            **6. Final Grammatical Range and Accuracy Score:**
+            Conclude with the final band score for GRA only. No further comments.
+            *Example:*
+            "Final Grammatical Range and Accuracy Score: 5"
+
+            Do not add any conversational closings, greetings, or encouragement to message again. Your response must end with the final score.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template(
+            """
+            **IELTS Writing Task 2 Question:**
+            {question}
+
+            **Student's Response:**
+            {student_response}
+            """
+        )
+    ])
+
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "question": state["original_question"],
+        "student_response": state["student_essay"]
+    })
+
+    return {"grammatical_range_and_accuracy": response.content}
+
+
+def aggregator(state: State):
+    print("--Summarizing--")
+    logger.info("Summarizing")
+
+    chat_prompt = ChatPromptTemplate.from_messages([
+        SystemMessagePromptTemplate.from_template(
+            """
+            You are a Senior IELTS Writing Assessor and Head Examiner. Your function is to receive four separate, detailed evaluations for a single IELTS Writing Task 2 essay and synthesize them into a final, holistic report for the student. The four evaluations you will receive correspond to the four official IELTS marking criteria: Task Response (TR), Coherence and Cohesion (C&C), Lexical Resource (LR), and Grammatical Range and Accuracy (GRA).
+
+            **Your Core Role and Directives:**
+
+            1.  **Synthesize, Do Not Re-evaluate:** Your most important instruction is to base your entire report *only* on the analysis and scores provided in the four expert reports you receive as input. Do NOT re-read or make your own judgments on the original student essay. You are to trust and summarize the findings of the specialist examiners.
+            2.  **Summarize Key Points:** For each of the four criteria, you must concisely summarize the main points made by the specialist examiner. This includes highlighting both the strengths ("What You Did Well") and the key areas for improvement that were identified.
+            3.  **Calculate the Overall Score:** You are responsible for calculating the final, overall IELTS band score for Writing Task 2. You must do this precisely according to the official IELTS calculation method.
+
+            **How to Calculate the Overall Band Score (Crucial Instructions):**
+
+            The Overall Band Score is the average of the four individual scores. You must follow this procedure exactly:
+            * **Formula:** Overall Score = (Task Response Score + Coherence and Cohesion Score + Lexical Resource Score + Grammatical Range and Accuracy Score) / 4
+            * **Official Rounding Rule:** The result of the average must be rounded to the nearest half-band.
+                * If the average ends in **.25**, you must round **UP** to the next half-band (e.g., an average of 6.25 becomes an Overall Score of **6.5**).
+                * If the average ends in **.75**, you must round **UP** to the next whole band (e.g., an average of 6.75 becomes an Overall Score of **7.0**).
+                * If the average ends in .0 or .5, it does not change (e.g., 6.0 remains 6.0; 6.5 remains 6.5).
+
+            * **Example Calculation 1:** Scores are TR=6, C&C=7, LR=6, GRA=6. Average = (6+7+6+6)/4 = 6.25. Your final reported score must be **6.5**.
+            * **Example Calculation 2:** Scores are TR=7, C&C=7, LR=6, GRA=7. Average = (7+7+6+7)/4 = 6.75. Your final reported score must be **7.0**.
+
+            **Your Output Structure (Follow this format precisely):**
+
+            You must generate a single, consolidated report in the following order and with these exact headings:
+
+            **Overall IELTS Writing Task 2 Feedback**
+
+            Here is a summary of your performance based on the four official IELTS scoring criteria.
+
+            **1. Task Response**
+            * **Strengths:** [Concisely summarize the positive points from the Task Response agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Task Response agent's report.]
+            * **Expert Score:** [State the score given by the Task Response agent.]
+
+            **2. Coherence and Cohesion**
+            * **Strengths:** [Concisely summarize the positive points from the Coherence and Cohesion agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Coherence and Cohesion agent's report.]
+            * **Expert Score:** [State the score given by the Coherence and Cohesion agent.]
+
+            **3. Lexical Resource (Vocabulary)**
+            * **Strengths:** [Concisely summarize the positive points from the Lexical Resource agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Lexical Resource agent's report.]
+            * **Expert Score:** [State the score given by the Lexical Resource agent.]
+
+            **4. Grammatical Range and Accuracy**
+            * **Strengths:** [Concisely summarize the positive points from the Grammatical Range and Accuracy agent's report.]
+            * **Areas for Improvement:** [Concisely summarize the weaknesses and recommendations from the Grammatical Range and Accuracy agent's report.]
+            * **Expert Score:** [State the score given by the Grammatical Range and Accuracy agent.]
+
+            ---
+
+            **Final Analysis and Overall Score**
+            * **Summative Comments:** [Provide a brief (2-3 sentences) holistic overview. Identify the primary areas holding the score back or the main strengths. For example: "Overall, your ability to structure your ideas is a clear strength. However, your final score is primarily limited by frequent grammatical errors and a narrow range of vocabulary, which sometimes prevent your arguments from being fully clear."]
+            * **Overall Band Score:** [State the final, calculated, and correctly rounded overall score.]
+
+            Do not add any conversational closings, greetings, or encouragement to message again. Your response must end with the final Overall Band Score.
+            """
+        ),
+        HumanMessagePromptTemplate.from_template(
+            """
+            Please generate a final report based on the following four expert evaluations.
+
+            **TASK RESPONSE REPORT:**
+            ---
+            {task_response_report}
+            ---
+
+            **COHERENCE AND COHESION REPORT:**
+            ---
+            {coherence_cohesion_report}
+            ---
+
+            **LEXICAL RESOURCE REPORT:**
+            ---
+            {lexical_resource_report}
+            ---
+
+            **GRAMMATICAL RANGE AND ACCURACY REPORT:**
+            ---
+            {grammatical_range_and_accuracy_report}
+            ---
+            """
+        )
+    ])
+    
+    chain = chat_prompt | model
+    response = chain.invoke({
+        "task_response_report": state["task_response"],
+        "coherence_cohesion_report": state["coherence_and_cohesion"],
+        "lexical_resource_report": state["lexical_resource"],
+        "grammatical_range_and_accuracy_report": state["grammatical_range_and_accuracy"]
+    })
+
+    logger.info("Final Report!")
+
+    return {"aggregated_result": response.content}
+

vendors/part2/state.py

@@ -0,0 +1,12 @@
+from typing import List, TypedDict, Union
+
+
+class State(TypedDict):
+    student_essay: str
+    original_question: str
+    task_response: str
+    coherence_and_cohesion: str
+    lexical_resource: str
+    grammatical_range_and_accuracy: str
+    estimated_band_score: float
+    aggregated_result: str

vendors/part2/workflow.py

@@ -0,0 +1,29 @@
+from langgraph.graph import StateGraph, START, END
+
+
+def workflow_fn(State, task_response, lexical_resource, grammatical_range_and_accuracy, coherence_and_cohesion, aggregator):
+    workflow = StateGraph(State)
+
+    workflow.add_node("Task Response", task_response)
+    workflow.add_node("Lexical", lexical_resource)
+    workflow.add_node("Grammar", grammatical_range_and_accuracy)
+    workflow.add_node("CC", coherence_and_cohesion)
+    workflow.add_node("Aggregator", aggregator)
+
+    workflow.add_edge(START, "Task Response")
+    workflow.add_edge(START, "Lexical")
+    workflow.add_edge(START, "Grammar")
+    workflow.add_edge(START, "CC")
+    workflow.add_edge("Task Response", "Aggregator")
+    workflow.add_edge("CC", "Aggregator")
+    workflow.add_edge("Grammar", "Aggregator")
+    workflow.add_edge("Lexical", "Aggregator")
+    workflow.add_edge("Aggregator", END)
+
+    workflow = workflow.compile()
+
+    with open("Workflow.md", "w") as f:
+        mermaid_code = workflow.get_graph().draw_mermaid()
+        f.write(f"```mermaid\n{mermaid_code}\n```")
+
+    return workflow