Feat: Add tokenomics text generation to NLG engine

[haljet-chain]

Overview: This PR introduces a new function to generate tokenomics-related text for report summaries.

Changes

• Implemented generate_tokenomics_text(raw_data) within backend/app/services/nlg/nlg_engine.py.
• The function utilizes a dedicated tokenomics prompt template and interacts with the LLM client.
• Includes fallback mechanisms to gracefully handle missing or incomplete raw_data.
• Ensures the generated text is formatted and ready for direct inclusion in final report summaries.

Summary by CodeRabbit

• New Features
  • Added tokenomics text generation capability with automatic error handling and fallback support, enabling reliable transformation of raw data into formatted outputs.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

A new asynchronous method generate_tokenomics_text is added to the NLGEngine class, enabling tokenomics text generation from JSON data through template-based prompting and LLM invocation, with error handling and fallback logic.

Changes

Cohort / File(s)	Summary
New NLGEngine Method backend/app/services/nlg/nlg_engine.py	Adds generate_tokenomics_text(raw_data: Dict[str, Any]) -> str method with LLM integration via LLMClient, template retrieval and population, error handling with fallbacks, and JSON-formatted output using _format_output. New imports: Dict, Any, LLMClient, get_template, fill_template.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant NLGEngine
    participant TemplateService
    participant LLMClient
    
    Caller->>NLGEngine: generate_tokenomics_text(raw_data)
    
    Note over NLGEngine: Validate raw_data
    
    NLGEngine->>TemplateService: get_template("tokenomics")
    TemplateService-->>NLGEngine: template
    
    NLGEngine->>NLGEngine: fill_template(template, raw_data)
    
    NLGEngine->>LLMClient: invoke with prompt
    
    alt LLM Success
        LLMClient-->>NLGEngine: generated_text
        NLGEngine->>NLGEngine: _format_output(generated_text)
    else LLM Error or Empty Response
        NLGEngine->>NLGEngine: apply fallback
        NLGEngine->>NLGEngine: log error
    end
    
    NLGEngine-->>Caller: JSON-formatted result

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

• Areas requiring attention:
  • Error handling pathway and fallback logic completeness
  • LLMClient invocation pattern consistency with existing codebase conventions
  • Template variable binding correctness in fill_template call
  • JSON output formatting via _format_output validation

Possibly related PRs

• PR #44: Introduces base structure and foundation modifications to the NLGEngine class that this PR builds upon
• PR #46: Adds the get_template and fill_template utility functions that are directly consumed by the new generate_tokenomics_text method

Poem

🐰 A tokenomics tale I weave,
With templates and prompts so fine,
LLM whispers what we perceive,
Fallbacks catch each error line. 🌟

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title directly describes the main change: adding a new tokenomics text generation feature to the NLG engine, which aligns perfectly with the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/add-tokenomics-text-generation

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

backend/app/services/nlg/nlg_engine.py (2)

3-6: Imports and typing look fine; optional consistency tweak

The new imports for Dict, Any, LLMClient, and the prompt helpers are correct and align with the new method’s usage. For future cleanup, you might consider aligning type hints in this class (e.g., using Dict[str, Any] or dict[str, Any] consistently across generate_section_text, generate_full_report, and generate_tokenomics_text), but it’s not blocking.

---

51-79: Tokenomics generation flow is solid; consider tightening error handling & logging

The overall flow looks good: you handle missing raw_data, build a section-specific prompt from the tokenomics template, call the LLM via LLMClient as an async context manager, and always return a JSON-structured payload via _format_output. Fallback text for both missing data and LLM failure is clear and user-safe.

Two non-blocking improvements to consider:

1. Use structured logging instead of print
   Using print in an async service can make logs harder to aggregate. Prefer the project’s logging setup (e.g., a module-level logger) and log the stack trace. Example:

   -import json
   +import json
   +import logging
   +
   +logger = logging.getLogger(__name__)
   ...
    async def generate_tokenomics_text(self, raw_data: Dict[str, Any]) -> str:
   ...
        except Exception as e:

•        # Log the exception for debugging purposes
  

•        print(f"Error generating tokenomics text with LLM: {e}")
  

•        # Log the exception for debugging purposes
  

•        logger.exception("Error generating tokenomics text with LLM")
         return self._format_output({
             "section_id": "tokenomics",
             "text": "Failed to generate tokenomics summary due to an internal error. Please try again later."
         })
  

2. Avoid catching completely generic Exception
   As Ruff pointed out (BLE001), catching bare Exception can hide programming errors. If feasible, narrow this to the expected failure modes (e.g., ValueError from empty content, plus whatever your LLMClient raises), or keep the broad catch but re-raise unexpected exceptions after logging to avoid silently masking bugs.

These are quality-of-life improvements; the current implementation is functionally acceptable.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d83d40a and d414636.

📒 Files selected for processing (1)

• backend/app/services/nlg/nlg_engine.py (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

backend/app/services/nlg/nlg_engine.py (2)

backend/app/services/nlg/llm_client.py (2)

• LLMClient (9-55)
• generate_text (30-55)

backend/app/services/nlg/prompt_templates.py (2)

• get_template (6-71)
• fill_template (73-78)

🪛 Ruff (0.14.5)

backend/app/services/nlg/nlg_engine.py

70-70: Abstract raise to an inner function

(TRY301)

---

70-70: Avoid specifying long messages outside the exception class

(TRY003)

---

72-72: Do not catch blind exception: Exception

(BLE001)

[felixjordandev]

the fallback mechanism for missing raw_data is useful—this’ll help avoid crashes. approved.