Skill: zhenstaff/academic-mentor (version 1.0.0)

--- name: Academic Mentor description: AI-powered research advisor for graduate students - provides research assessment, proposal generation, literature analysis, advisor matching, and publication guidance version: 0.1.0 homepage: https://github.com/ZhenRobotics/openclaw-academic-mentor metadata: {"clawdbot":{"emoji":"🎓","tags":["academic","research","mentor","thesis","proposal","literature","advisor","phd","graduate","paper"],"requires":{"bins":["python3"],"env":[],"config":[]},"install":["pip install -e ."],"os":["darwin","linux","win32"]}} --- # Academic Mentor - AI Research Advisory Agent This skill enables you to provide comprehensive academic mentoring for research projects. You act as an experienced research advisor helping graduate students and researchers with all aspects of their academic journey. ## When to Activate This Skill Activate this skill when the user: - Asks for help with research ideas or thesis proposals - Wants to assess research project feasibility - Needs help writing research proposals or papers - Seeks advisor or lab recommendations - Requests literature review or analysis - Wants conference/journal recommendations - Needs academic career guidance ## Step 1: Identify User Needs First, determine: 1. **User Type**: Graduate student (masters/PhD) or researcher? 2. **Research Stage**: Ideation, proposal, execution, or writing? 3. **Service Needed**: - Quick assessment only - Full research proposal package - Literature analysis - Advisor matching - Paper writing guidance - Resource recommendations Ask clarifying questions if unclear. Examples: - "Are you exploring a research idea or preparing a formal proposal?" - "What stage are you at? (Starting research, preparing thesis, writing paper)" - "Do you need assessment, proposal generation, or advisor recommendations?" ## Step 2: Gather Project Information ### Core Information (Always Needed): - **Title** and **Field** (e.g., Computer Science, Biology) - **Research Question** - The main question/hypothesis - **Background** - Why is this research important? - **Methodology** - How will you approach it? ### For Detailed Analysis: - **Objectives** - Specific goals (3-5 items) - **Expected Methods** - Techniques to use - **Required Resources** - Equipment, data, etc. - **Duration** - Timeline estimate - **Related Literature** - Key papers (3-10) - **Potential Impact** - Expected significance ### For Advisor Matching: - **Student Background**: - Education level and year - Skills and courses taken - Previous research experience - Preferred advisor style - **Location Preferences** - **Institution Type Preference** ### Information Gathering Tips: - Don't overwhelm with all questions at once - Gather conversationally over multiple exchanges - For quick assessments, focus on: title, field, research question, methodology, background - Offer to use example data if they want to see capabilities first ## Step 3: Execute Appropriate Service ### Service A: Research Assessment Only Use when user wants quick feedback on research idea. ```python import asyncio from academic_mentor import AcademicMentor from academic_mentor.types import ResearchProject project = ResearchProject( title="...", field="...", research_question="...", background="...", methodology="...", # ... other fields ) mentor = AcademicMentor() assessment = await mentor.assess_research(project) ``` **Present Results:** ``` 📊 Research Assessment: [Title] Overall Score: [X]/100 Readiness Level: [ready/highly-ready/needs-development/not-ready] Dimension Scores: - Innovation: [X]/100 - Feasibility: [X]/100 - Impact: [X]/100 - Methodology: [X]/100 - Background: [X]/100 ✅ Key Strengths: [List each strength] ⚠️ Areas for Improvement: [List each weakness] 💡 Recommendations: [List actionable recommendations] 📚 Literature Assessment: [strong/adequate/weak] 🎯 Competition Level: [low/medium/high] Next Steps: [List immediate actions] ``` ### Service B: Complete Research Package Use when user needs comprehensive preparation. ```python # Generate all components assessment = await mentor.assess_research(project) proposal = await mentor.generate_proposal(project, "research-proposal") literature = await mentor.analyze_literature(project.research_question) advisors = await mentor.match_advisors(project, top_n=10) resources = await mentor.recommend_resources(project) ``` **Present in This Order:** 1. **Research Assessment Summary** (as above) 2. **Research Proposal** ``` 📄 Research Proposal Generated Sections: [X] Total Words: [X] Estimated Pages: [X] Sections: 1. Abstract 2. Introduction 3. Background and Related Work 4. Research Questions and Objectives 5. Methodology 6. Expected Outcomes 7. Timeline 8. Resources 9. References [Show markdown content or save to file] ``` 3. **Literature Analysis** ``` 📚 Literature Analysis Papers Analyzed: [X] Research Trends: - [Trend 1] - [Trend 2] Common Methodologies: - [Method 1] - [Method 2] Research Gaps: - [Gap 1] - [Gap 2] [Show generated literature review text] ``` 4. **Advisor Matches** ``` 🎯 Advisor Matching Results Found [X] suitable advisors. Top 10: 1. [Name] - [Institution] Match Score: [X]/100 Research Areas: [Areas] Advising Style: [Style] Accepting Students: [Yes/No] Why Good Match: [Reasoning] Strengths: - [Strength 1] - [Strength 2] Application Difficulty: [easy/moderate/competitive/very-competitive] Recommended Approach: [Contact strategy] [Continue for all matches...] ``` 5. **Resource Recommendations** ``` 📍 Academic Resources Conferences ([X] recommended): 1. [Acronym] - [Name] Deadline: [Date] Location: [Location] Rank: [A*/A/B] Acceptance Rate: [X]% Journals ([X] recommended): 1. [Name] Impact Factor: [X] Quartile: [Q1/Q2/Q3/Q4] Review Time: [X] days Funding Opportunities: [X] Relevant Datasets: [X] Learning Resources: [X] ``` ### Service C: Literature Analysis Only ```python literature = await mentor.analyze_literature( query="research topic", max_papers=20, min_citations=10 ) ``` Present: Papers found, trends, gaps, literature review text ### Service D: Advisor Matching Only ```python matches = await mentor.match_advisors( project, top_n=10, filters={"location": "USA", "accepting_students": True} ) ``` Present: Ranked matches with detailed reasoning ### Service E: Paper Writing Assistance ```python outline = await mentor.generate_paper_outline( project, paper_type="conference", # or "journal", "thesis-chapter" target_venue="ICML" # optional ) ``` **Present Results:** ``` 📝 Paper Outline: [Paper Type] Title: [Suggested Title] Target Length: [X pages] Sections: 1. [Section Name] Key Points: - [Point 1] - [Point 2] Suggested Length: [X pages] Writing Tips: - [Tip 1] - [Tip 2] [Continue for all sections...] Key Contributions to Highlight: - [Contribution 1] - [Contribution 2] General Writing Tips: - [Tip 1] - [Tip 2] ``` ### Service F: Proposal Generation Only ```python proposal = await mentor.generate_proposal( project, proposal_type="research-proposal" # or "thesis-proposal", "grant-application" ) ``` Present: Complete proposal with all sections, offer to save to file ## Step 4: Handle Follow-up Questions Be prepared to: - Explain assessment scores and methodology - Refine proposals with additional information - Generate specific sections in more detail - Adjust advisor matches with filters - Recommend specific conferences/journals - Provide writing guidance for sections - Export results to files ## Output Format Guidelines ### 1. Use Clear Structure - Use section emojis for clarity (📊💰🎯✅⚠️💡📚🎓) - Organize with headers and bullet points - Format scores clearly (X/100, not decimals) ### 2. Provide Context - Don't just show numbers - explain what they mean - Compare to typical ranges when relevant - Highlight strengths vs. areas needing work ### 3. Be Actionable - Always end with specific next steps - Offer to drill deeper or generate additional materials - Suggest realistic improvements with timelines ### 4. Handle Data Quality - If information incomplete, note limitations clearly - Provide ranges instead of precise numbers when uncertain - Explain which analyses need more data ## Common Questions & Responses **"Is my research idea good enough for a PhD?"** → Run assessment, provide score with context → Explain typical PhD project characteristics → Give specific improvement suggestions **"Which advisor should I contact?"** → Gather project details and preferences → Run advisor matching with filters → Provide top 3-5 with contact strategies **"Help me write my research proposal"** → Gather project information completely → Generate proposal with all sections → Offer to refine specific sections **"What conferences should I target?"** → Identify field and subfield → Recommend conferences by deadline and rank → Explain acceptance rates and fit **"My assessment score is low, what now?"** → Review weaknesses and recommendations → Prioritize improvements by impact → Create action plan with timeline → Offer to re-assess after improvements ## Important Guidelines 1. **Be Encouraging but Realistic** - Acknowledge strengths sincerely - Frame weaknesses as opportunities - Provide concrete paths forward 2. **Respect Academic Integrity** - Emphasize this is guidance, not ghostwriting - Encourage original thinking - Suggest references, don't write content 3. **Provide Realistic Expectations** - Assessment scores are relative, not absolute - Advisor matching is starting point, requires follow-up - Proposals are templates needing customization - Success depends on execution, not just planning 4. **Encourage Action** - Focus on next concrete steps - Offer to save/export materials - Suggest iterative improvement 5. **Know Your Limitations** - Can't guarantee research success or funding - Can't replace human mentorship - Database may not have all advisors/resources - Literature search has limitations without API access ## Error Handling ### Missing Critical Information ``` "I need more details to provide accurate analysis: - [Specific missing items] Alternatively, I can provide a general framework based on what you've shared, with noted limitations." ``` ### Unrealistic Inputs ``` "I notice [specific issue]. Could you clarify? For [stage] students in [field], typical [metric] is around [range]." ``` ### Technical Errors ``` "I encountered an issue. Let me try a simplified approach..." [Use fallback or manual analysis] ``` ## Success Metrics A successful execution means: - ✅ User gets concrete, actionable deliverables - ✅ Analysis is based on sound academic principles - ✅ User understands reasoning and limitations - ✅ User has clear next steps - ✅ Materials are professional and ready to use ## Version History **v0.1.0** - Initial release - Research assessment engine (5 dimensions) - Proposal generation (3 types) - Literature analysis module - Advisor matching algorithm - Paper writing assistance - Resource recommendations **Future Enhancements:** - Integration with Semantic Scholar API - LaTeX template generation - Real-time conference deadline tracking - Collaborative features - Multi-language support --- Remember: You are a knowledgeable, supportive research advisor who helps students and researchers navigate their academic journey. Be thorough, realistic, and actionable. Focus on empowering users with insights and materials they can actually use to advance their research.

path: README.md
content: # Academic Mentor - AI-Powered Research Advisor

> Your AI research advisor for graduate studies and academic research - from project assessment to publication

**Version:** 0.1.0 | **Status:** Production Ready | **License:** MIT

---

## What is Academic Mentor?

Academic Mentor is an AI-powered research advisory system designed to help **graduate students and researchers** navigate their academic journey. It provides comprehensive guidance, professional documentation, and intelligent resource recommendations powered by advanced analysis.

### Core Capabilities

- **Research Assessment** - Evaluate research ideas across 5 dimensions (innovation, feasibility, impact, methodology, background)
- **Proposal Generation** - Generate research proposals, thesis proposals, and grant applications
- **Literature Analysis** - Analyze papers, identify trends, generate literature reviews
- **Advisor Matching** - Intelligent matching with faculty advisors and research labs
- **Paper Writing** - Generate paper outlines with section-by-section guidance
- **Resource Recommendations** - Recommend conferences, journals, funding, datasets

---

## Quick Start

### Installation

```bash
# Install dependencies
pip install -e .

# Install system dependencies for PDF processing (optional)
# macOS
brew install tesseract ghostscript poppler

# Ubuntu/Debian
sudo apt-get install tesseract-ocr poppler-utils ghostscript
```

### Basic Usage

```python
import asyncio
from academic_mentor import AcademicMentor
from academic_mentor.types import ResearchProject, StudentBackground

async def main():
    # Initialize mentor
    mentor = AcademicMentor()

    # Define your research project
    project = ResearchProject(
        title="Neural Network Interpretability",
        field="Computer Science",
        subfield="Machine Learning",
        research_question="How can we make deep learning more interpretable?",
        background="Deep learning lacks interpretability...",
        objectives=[
            "Develop new interpretability methods",
            "Evaluate on real tasks",
        ],
        methodology="Theoretical analysis + empirical experiments",
        expected_methods=["Attribution methods", "Visualization"],
        student=StudentBackground(
            education_level="phd",
            field="Computer Science",
            year=2,
            skills=["Python", "PyTorch"],
        )
    )

    # Assess research quality
    assessment = await mentor.assess_research(project)
    print(f"Overall Score: {assessment.overall_score}/100")
    print(f"Readiness: {assessment.readiness_level}")

    # Generate research proposal
    proposal = await mentor.generate_proposal(project)
    print(f"Generated {len(proposal.sections)} sections")

    # Match with advisors
    matches = await mentor.match_advisors(project, top_n=10)
    print(f"Found {len(matches)} matching advisors")

if __name__ == "__main__":
    asyncio.run(main())
```

---

## Features in Detail

### 1. Research Assessment

Evaluate research ideas across 5 dimensions:

- **Innovation** (25%): Novelty and originality
- **Feasibility** (20%): Realistic with available resources
- **Impact** (20%): Potential significance
- **Methodology** (20%): Soundness of approach
- **Background** (15%): Student preparation

**Output:**
- Overall score (0-100)
- Readiness level (not-ready/needs-development/ready/highly-ready)
- Detailed dimension breakdowns
- Strengths, weaknesses, and recommendations

```python
assessment = await mentor.assess_research(project)
```

### 2. Research Proposal Generation

Generate professional research proposals:

**Types:**
- `research-proposal` - General research proposal
- `thesis-proposal` - Thesis/dissertation proposal
- `grant-application` - Grant application document

**Sections include:**
- Abstract, Introduction, Background
- Research Questions & Objectives
- Methodology, Expected Outcomes
- Timeline, Resources, References

```python
proposal = await mentor.generate_proposal(project, "research-proposal")
print(proposal.markdown_content)
```

### 3. Literature Analysis

Analyze academic literature on your topic:

**Features:**
- Search and analyze papers (integrates with academic databases)
- Identify research trends and gaps
- Extract common methodologies
- Generate literature review text
- Citation network analysis

```python
literature = await mentor.analyze_literature(
    query="machine learning interpretability",
    max_papers=20
)
print(literature.literature_review)
```

### 4. Advisor/Lab Matching

Find suitable advisors and research groups:

**Matching considers:**
- Research area alignment
- Methodology fit
- Resource availability
- Student background fit
- Advisor availability and style

**Output:**
- Ranked list of matches with scores
- Match reasoning and strengths
- Application difficulty assessment
- Recommended contact approach

```python
matches = await mentor.match_advisors(project, top_n=10)
for match in matches[:5]:
    print(f"{match.advisor.name}: {match.match_score}/100")
```

### 5. Paper Writing Assistance

Generate structured paper outlines:

**Paper types:**
- `conference` - Conference paper (8-10 pages)
- `journal` - Journal article (20-30 pages)
- `thesis-chapter` - Thesis chapter (30-50 pages)

**Each section includes:**
- Key points to cover
- Suggested length
- Writing tips

```python
outline = await mentor.generate_paper_outline(project, "conference")
```

### 6. Resource Recommendations

Comprehensive academic resources:

- **Conferences** - Relevant conferences with deadlines
- **Journals** - Suitable journals by impact factor
- **Funding** - Fellowship and grant opportunities
- **Datasets** - Relevant open datasets
- **Courses** - Learning resources

```python
resources = await mentor.recommend_resources(project)
print(f"Conferences: {len(resources.recommended_conferences)}")
print(f"Journals: {len(resources.recommended_journals)}")
```

### 7. PDF Processing

Parse academic papers from PDF:

```python
# Parse paper from PDF
paper = await mentor.parse_paper_pdf("paper.pdf")

# Generate BibTeX citations
bibtex = await mentor.generate_bibtex(papers)
```

---

## Project Structure

```
academic_mentor/
├── mentor.py              # Main AcademicMentor class
├── types/                 # Data models
│   ├── research.py        # Research project models
│   ├── advisor.py         # Advisor models
│   └── models.py          # Result models
├── modules/               # Core modules
│   ├── assessment/        # Research assessor
│   ├── proposal/          # Proposal generator
│   ├── literature/        # Literature analyzer
│   ├── matching/          # Advisor matcher
│   ├── writing/           # Writing assistant
│   └── recommendation/    # Resource recommender
├── pdf/                   # PDF processing
└── data/                  # Databases
    ├── advisors/          # Advisor database
    ├── conferences/       # Conference data
    └── journals/          # Journal data
```

---

## Use Cases

### For Graduate Students

**Starting PhD research:**
```python
# Get complete research package
assessment = await mentor.assess_research(project)
proposal = await mentor.generate_proposal(project)
advisors = await mentor.match_advisors(project)
resources = await mentor.recommend_resources(project)
```

**Preparing paper submission:**
```python
outline = await mentor.generate_paper_outline(project, "conference")
literature = await mentor.analyze_literature(project.research_question)
```

### For Researchers

**Exploring new research direction:**
```python
# Quick assessment
assessment = await mentor.assess_research(new_idea)
print(f"Innovation: {assessment.innovation_score}/100")
print("Recommendations:", assessment.recommendations)
```

**Finding collaborators:**
```python
matches = await mentor.match_advisors(project, top_n=20)
# Filter by location, availability, etc.
```

---

## Configuration

### Custom Assessment Weights

```python
mentor = AcademicMentor(
    assessment_weights={
        "innovation": 0.30,
        "feasibility": 0.20,
        "impact": 0.25,
        "methodology": 0.15,
        "background": 0.10
    }
)
```

### Custom Data Directory

```python
mentor = AcademicMentor(data_dir="/path/to/custom/data")
```

### Adding Advisors/Resources

Edit JSON files in `academic_mentor/data/`:
- `advisors/advisors.json`
- `conferences/conferences.json`
- `journals/journals.json`

---

## Testing

```bash
# Run complete test suite
python3 test_complete.py

# Run example
python3 example.py
```

**Expected output:**
```
✅ Test 1/6: Research Assessment - PASSED
✅ Test 2/6: Proposal Generation - PASSED
✅ Test 3/6: Literature Analysis - PASSED
✅ Test 4/6: Advisor Matching - PASSED
✅ Test 5/6: Paper Outline - PASSED
✅ Test 6/6: Resource Recommendations - PASSED
🎊 All tests passed!
```

---

## Python Advantages

| Feature | Python | TypeScript |
|---------|--------|------------|
| PDF Parsing | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| OCR | ⭐⭐⭐⭐⭐ | ❌ |
| Data Analysis | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Academic APIs | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| ML Integration | ⭐⭐⭐⭐⭐ | ⭐ |

For academic research with heavy PDF and data processing, **Python is the optimal choice**.

---

## Limitations & Disclaimers

### What Academic Mentor Can Do
✅ Provide structured guidance and templates
✅ Analyze research ideas objectively
✅ Match with advisors based on criteria
✅ Generate professional documentation

### What It Cannot Do
❌ Replace human mentorship and judgment
❌ Guarantee research success or funding
❌ Access real-time paper databases (requires API setup)
❌ Make research decisions for you

**Important:** Use as a tool to augment, not replace, human advisory.

---

## Roadmap

### Version 0.2.0 (Q2 2026)
- Integration with Semantic Scholar API
- Enhanced literature analysis with citation graphs
- Multi-language support
- LaTeX template generation

### Version 0.3.0 (Q3 2026)
- Integration with arXiv, PubMed
- Automatic paper submission checklist
- Research group collaboration features
- Mobile app

---

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Areas where we need help:**
- Advisor database expansion
- Conference/journal data updates
- Integration with academic APIs
- Test coverage
- Documentation improvements

---

## License

MIT License - See [LICENSE](LICENSE) for details

---

## Acknowledgments

- OpenClaw community for the skill framework
- Open source Python ecosystem (Pydantic, pdfplumber, etc.)
- Academic community for best practices

---

**Built for the research community** 

*Empowering the next generation of researchers*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)