---
license: mit
language:
  - en
  - de
library_name: transformers
tags:
  - reasoning
  - multi-step
  - planning
  - strategic-analysis
  - enterprise
  - wemake
  - clarity
  - orchestration
---

# Clarity-MR-1: Advanced Multi-Step Reasoning Model

Clarity-MR-1 is WeMake's specialized AI model designed for complex multi-step reasoning and strategic planning tasks. As the "thinker" of the Clarity ecosystem, it excels at logical deduction, analytical problem-solving, and structured decision-making processes. This model serves as the planning and reasoning agent in WeMake's orchestrated multi-agent AI system, addressing the "reasoning gap" in general-purpose models.

## 🎯 Overview

### Model Description and Purpose

Clarity-MR-1 represents WeMake's focused approach to advanced reasoning capabilities, specifically engineered for:

- Complex logical deduction requiring multi-step analysis
- Strategic planning and decision-making processes
- Analytical problem-solving across diverse domains
- Structured reasoning with transparent thought processes
- Planning coordination within orchestrated AI workflows

### Model Designation

The "MR-1" designation indicates:

- M: Multi-step processing capability
- R: Reasoning specialization (as opposed to execution or perception)
- 1: First-generation reasoning architecture optimized for enterprise contexts

### Architecture Overview

Clarity-MR-1 employs advanced reasoning architectures that:

- Implement structured multi-step reasoning processes
- Maintain transparent logical chains for auditability
- Support iterative refinement of analytical conclusions
- Enable complex problem decomposition and synthesis
- Integrate seamlessly with orchestration frameworks

## 📥 Download Models

|      Model       | #Total Params | #Activated Params | Context Length |                             Download                             |
| :--------------: | :-----------: | :---------------: | :------------: | :--------------------------------------------------------------: |
| Clarity-MR-1 |     671B      |        37B        |      128K      |   [🤗 HuggingFace](https://huggingface.co/WeMake/Clarity-MR-1)   |
|   Clarity-MX-2   |      TBA      |        TBA        |      TBA       |   [🤗 HuggingFace](https://huggingface.co/WeMake/Clarity-MX-2)   |
| Clarity-MK-alpha |      TBA      |        TBA        |      TBA       | [🤗 HuggingFace](https://huggingface.co/WeMake/Clarity-MK-alpha) |

## 💬 Chat Template

Clarity-MR-1 uses a sophisticated chat template system that supports both thinking and non-thinking modes, as well as tool calling capabilities. The template details are described in `tokenizer_config.json` and [`assets/chat_template.jinja`](assets/chat_template.jinja).

### Template Structure

The chat template uses special tokens to control the model's behavior:

- `<｜begin▁of▁sentence｜>`: Start of conversation
- `<｜User｜>`: User message delimiter
- `<｜Assistant｜>`: Assistant response delimiter
- `<｜end▁of▁sentence｜>`: End of turn
- `<think>` / `</think>`: Thinking mode delimiters
- Tool calling tokens for structured function calls

### Non-Thinking Mode

#### First Turn

```
<｜begin▁of▁sentence｜>{system_prompt}<｜User｜>{query}<｜Assistant｜></think>
```

#### Multi-Turn

```
<｜begin▁of▁sentence｜>{system_prompt}<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>
```

### Thinking Mode

#### First Turn

```
<｜begin▁of▁sentence｜>{system_prompt}<｜User｜>{query}<｜Assistant｜><think>
```

#### Multi-Turn

```
<｜begin▁of▁sentence｜>{system_prompt}<｜User｜>{query}<｜Assistant｜></think>{response}<｜end▁of▁sentence｜>...<｜User｜>{query}<｜Assistant｜><think>
```

### Tool Calling Format

Clarity-MR-1 supports structured tool calling in non-thinking mode:

```
<｜begin▁of▁sentence｜>{system_prompt}

## Tools
You have access to the following tools:

### {tool_name}
Description: {description}
Parameters: {json.dumps(parameters)}

<｜User｜>{query}<｜Assistant｜></think>
```

Important: Always adhere to this exact format for tool use:

```
<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>tool_call_name<｜tool▁sep｜>tool_call_arguments<｜tool▁call▁end｜>{additional_tool_calls}<｜tool▁calls▁end｜>
```

Where:

- `tool_call_name` must be an exact match to one of the available tools
- `tool_call_arguments` must be valid JSON that strictly follows the tool's Parameters Schema
- For multiple tool calls, chain them directly without separators or spaces

## 🛠️ Agent Frameworks

### Code Agent

Clarity-MR-1 supports various code agent frameworks for software development tasks. The model can:

- Execute bash commands for system operations
- Create, edit, and manage files using structured editing tools
- Implement complex software solutions with multi-step reasoning
- Debug and optimize code with analytical approaches

Example Code Agent Workflow:

1. Analysis: Break down the coding task into logical components
2. Planning: Create a structured implementation plan
3. Execution: Use appropriate tools (bash, file editor) to implement solutions
4. Validation: Test and verify the implementation
5. Optimization: Refine and improve the solution

For detailed examples, see [`code_agent_trajectory.html`](assets/code_agent_trajectory.html).

### Search Agent

Clarity-MR-1 features specialized search agent capabilities for information retrieval and analysis:

#### Search Process

1. Query Analysis: Break down complex questions into searchable components
2. Multi-Query Generation: Create up to 5 parallel search queries using `||` separator
3. Information Synthesis: Analyze and combine search results
4. Citation Management: Provide proper citations using `[citation:x]` format

#### Search Query Guidelines

- Use generalized, search engine-friendly keywords
- Avoid relative terms like "third author" or "the following year"
- Keep queries short (≤15 characters ideally)
- Remove unnecessary auxiliary words and conjunctions
- Use original language for non-English sources
- Split complex questions into separate queries

#### Example Search Workflow

```
<｜search▁begin｜>
{step-by-step reasoning}
<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>search<｜tool▁sep｜>{"questions":"query1||query2||query3"}<｜tool▁call▁end｜><｜tool▁calls▁end｜>
{analysis of results}
<｜search▁end｜>

{final answer with citations}
```

For detailed examples, see:

- [`search_tool_trajectory.html`](assets/search_tool_trajectory.html)
- [`search_python_tool_trajectory.html`](assets/search_python_tool_trajectory.html)

## 🎯 Intended Uses and Limitations

### Primary Use Cases

- Strategic business analysis requiring multi-faceted evaluation
- Complex problem decomposition and solution development
- Risk assessment and scenario planning
- Decision support systems for executive and management teams
- Research and analysis tasks requiring deep logical reasoning
- Planning coordination in multi-agent AI systems

### Recommended Applications

- Financial Analysis: Risk assessment, investment planning, market analysis
- Legal Strategy: Case analysis, regulatory compliance, strategic planning
- Business Intelligence: Market research, competitive analysis, operational planning
- Academic Research: Literature analysis, hypothesis generation, methodology design
- Technical Planning: Architecture design, system optimization, troubleshooting
- Integration: Seamless integration with WeMake's Clarity Orchestrator

### Performance Characteristics

- Reasoning Depth: Exceptional multi-step logical analysis
- Transparency: Auditable thought processes and decision chains
- Consistency: Reliable analytical frameworks across domains
- Scalability: Efficient processing of complex reasoning tasks

### Limitations

- Computational Cost: Higher resource requirements compared to execution-focused models
- Processing Time: Longer analysis time for complex reasoning tasks
- Task Specialization: Not optimized for high-throughput simple tasks (use [Clarity-MX-2](https://huggingface.co/WeMake/Clarity-MX-2) instead)
- Multimodal Constraints: Limited multimodal reasoning (use [Clarity-MK-Alpha](https://huggingface.co/WeMake/Clarity-MK-Alpha) for multimodal analysis)
- Input Structure: Requires well-structured input for optimal reasoning performance

### Out-of-Scope Uses

- High-volume, simple text processing tasks
- Real-time conversational applications requiring immediate responses
- Basic content generation without analytical requirements
- Multimodal content analysis (images, audio, video)
- Tasks not requiring complex logical reasoning

## 📊 Training Data Overview

### Data Sources

- Academic Datasets: Logic, mathematics, and analytical reasoning domains
- Business Cases: Documented decision-making processes from diverse industries
- Strategic Documents: Planning materials from organizational contexts
- Legal Analysis: Regulatory analysis examples with structured reasoning
- Scientific Research: Papers demonstrating systematic analytical approaches

### Data Characteristics

- Reasoning Patterns: Multi-step logical processes and decision trees
- Domain Coverage: Cross-industry analytical and strategic contexts
- Language Focus: European business languages with analytical precision
- Quality Standards: Expert-validated reasoning chains and conclusions
- Complexity Levels: Graduated from simple to highly complex reasoning tasks

### Ethical Data Practices

- Source Transparency: Reasoning examples from public and licensed materials
- Privacy Protection: Business cases anonymized to protect organizational privacy
- PII Removal: Systematic removal of personally identifiable information
- Bias Assessment: Regular evaluation across reasoning domains and cultural contexts
- Quality Validation: Continuous validation of logical consistency and analytical accuracy

## 📈 Performance Metrics

### Reasoning Benchmarks

| Metric                   | Score | Comparison       |
| ------------------------ | ----- | ---------------- |
| Logical Consistency      | TBA   | Industry Leading |
| Problem Decomposition    | TBA   | Superior         |
| Solution Quality         | TBA   | Excellent        |
| Reasoning Transparency   | TBA   | Best-in-Class    |
| Cross-Domain Performance | TBA   | Outstanding      |

### Efficiency Metrics

| Metric               | Value | Notes                           |
| -------------------- | ----- | ------------------------------- |
| Reasoning Depth      | TBA   | Multi-level analysis capability |
| Processing Time      | TBA   | Optimized for complex tasks     |
| Resource Utilization | TBA   | Efficient parameter activation  |
| Scalability          | TBA   | Enterprise-grade performance    |

### Comparative Performance

- vs. OpenAI 'o' Series: TBA - Competitive reasoning depth with superior transparency
- vs. Anthropic Claude (Extended Thinking): TBA - Enhanced structured reasoning
- vs. General-Purpose Models: TBA - Specialized reasoning advantage
- Integration Advantage: TBA - Seamless orchestration capabilities

## ⚖️ Ethical Considerations

### Alignment with WeMake Ethics Policy

Clarity-MR-1 development strictly adheres to WeMake's comprehensive ethics framework:

#### Reasoning Transparency

- Auditable Processes: All analytical processes are traceable and explainable
- Decision Chains: Clear documentation of reasoning steps and conclusions
- Assumption Clarity: Explicit identification of analytical assumptions and limitations
- Confidence Levels: Transparent communication of uncertainty and confidence

#### Bias Mitigation

- Systematic Assessment: Regular evaluation of reasoning biases across domains
- Cultural Sensitivity: Balanced analysis considering multiple perspectives
- Correction Mechanisms: Continuous improvement of bias detection and mitigation
- Diverse Training: Multi-cultural and multi-domain reasoning examples

#### Privacy Protection

- GDPR Compliance: Full adherence to European data protection regulations
- Data Minimization: Processing only necessary information for reasoning tasks
- Anonymization: Systematic removal of identifying information from examples
- Secure Processing: Enterprise-grade security for sensitive analytical tasks

#### Human Oversight

- Advisory Role: Model outputs serve as decision support, not autonomous decisions
- Validation Requirements: Mandatory human review for critical strategic recommendations
- Escalation Protocols: Clear procedures for complex or high-stakes decisions
- Responsibility Chains: Defined accountability for reasoning-based recommendations

### Decision Support Responsibilities

- Context Awareness: Recognition of organizational and cultural contexts
- Stakeholder Consideration: Balanced analysis considering multiple interests
- Risk Communication: Clear articulation of analytical risks and limitations
- Ethical Boundaries: Respect for legal, ethical, and organizational constraints

### Environmental and Social Impact

- Computational Efficiency: Optimized reasoning processes to minimize resource consumption
- Sustainable Infrastructure: European deployment with renewable energy focus
- Social Benefit: Enhanced decision-making for positive organizational impact
- Responsible Innovation: Continuous assessment of societal implications

## 🚀 Usage Instructions

### Getting Started

#### Prerequisites

- WeMake API access with reasoning model permissions
- Understanding of complex reasoning task requirements
- Appropriate security and authentication configurations
- Structured input preparation for optimal reasoning performance

#### Basic Implementation

```python
# Example API integration for complex reasoning
import requests
import json

# API Configuration
api_endpoint = "https://api.wemake.cx/clarity-mr-1"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Reasoning Task Configuration
payload = {
    "prompt": "Analyze the strategic risks and opportunities in our Q4 market expansion plan, considering regulatory, competitive, and operational factors.",
    "reasoning_mode": "thinking",  # or "non-thinking"
    "reasoning_depth": "comprehensive",
    "output_format": "structured_analysis",
    "max_tokens": 2048,
    "temperature": 0.2,
    "thinking_enabled": True
}

# Execute Reasoning Task
response = requests.post(api_endpoint, json=payload, headers=headers)
result = response.json()

# Process Results
if result.get("success"):
    reasoning_chain = result.get("thinking_process")
    final_analysis = result.get("response")
    confidence_score = result.get("confidence")

    print(f"Analysis Confidence: {confidence_score}")
    print(f"Reasoning Process: {reasoning_chain}")
    print(f"Final Analysis: {final_analysis}")
else:
    print(f"Error: {result.get('error')}")
```

#### Tool Integration Example

```python
# Code Agent Integration
code_agent_payload = {
    "prompt": "Debug the performance issue in our data processing pipeline",
    "tools": [
        {
            "name": "bash",
            "description": "Execute system commands",
            "parameters": {"command": "string"}
        },
        {
            "name": "file_editor",
            "description": "Edit and analyze code files",
            "parameters": {"action": "string", "file_path": "string"}
        }
    ],
    "reasoning_mode": "thinking",
    "max_iterations": 5
}

# Search Agent Integration
search_agent_payload = {
    "prompt": "Research the latest developments in quantum computing applications for financial modeling",
    "tools": [
        {
            "name": "search",
            "description": "Search the web for information",
            "parameters": {"questions": "string"}
        }
    ],
    "citation_format": "academic",
    "max_search_queries": 5
}
```

### Configuration Parameters

| Parameter              | Type    | Default      | Description                                |
| ---------------------- | ------- | ------------ | ------------------------------------------ |
| `reasoning_mode`       | string  | "thinking"   | "thinking" or "non-thinking"               |
| `reasoning_depth`      | string  | "standard"   | "basic", "standard", "comprehensive"       |
| `temperature`          | float   | 0.2          | Creativity vs consistency (0.0-1.0)        |
| `max_tokens`           | integer | 2048         | Maximum response length                    |
| `thinking_enabled`     | boolean | true         | Enable transparent reasoning               |
| `confidence_threshold` | float   | 0.7          | Minimum confidence for responses           |
| `output_format`        | string  | "structured" | "structured", "narrative", "bullet_points" |

### Advanced Features

#### Multi-Step Reasoning

```python
# Complex multi-step analysis
multi_step_config = {
    "reasoning_steps": [
        "problem_identification",
        "stakeholder_analysis",
        "risk_assessment",
        "solution_generation",
        "impact_evaluation"
    ],
    "step_validation": True,
    "iterative_refinement": True
}
```

#### Integration with Clarity Orchestrator

```python
# Orchestrated workflow integration
orchestrator_config = {
    "workflow_id": "strategic_analysis_v2",
    "agent_role": "reasoning_coordinator",
    "collaboration_mode": "sequential",
    "handoff_criteria": "reasoning_complete"
}
```

## 🔧 Troubleshooting

### Common Issues

#### Reasoning Quality Issues

- Problem: Shallow or incomplete analysis
- Solution: Increase `reasoning_depth` to "comprehensive" and enable `thinking_enabled`
- Prevention: Provide structured, detailed prompts with clear analytical requirements

#### Performance Issues

- Problem: Slow response times
- Solution: Optimize `max_tokens` and consider using "standard" reasoning depth for less complex tasks
- Alternative: Use Clarity-MX-2 for simpler tasks requiring faster responses

#### Tool Calling Errors

- Problem: Invalid tool call format
- Solution: Ensure exact adherence to the specified tool calling format with proper token delimiters
- Debug: Check tool name matching and JSON parameter validation

### Best Practices

1. Structured Prompts: Provide clear, well-structured prompts for optimal reasoning
2. Appropriate Complexity: Match reasoning depth to task complexity
3. Human Validation: Always validate critical strategic decisions
4. Iterative Refinement: Use multi-turn conversations for complex analyses
5. Resource Management: Monitor computational costs for extensive reasoning tasks

## 📄 License

This repository and the model weights are licensed under the [MIT License](LICENSE).

## 📞 Contact

For questions, issues, or collaboration opportunities:

- Email: [research@wemake.cx](mailto:research@wemake.cx)
- Community: [Hugging Face Discussions](https://huggingface.co/WeMake/Clarity-MR-1/discussions)

---

_Clarity-MR-1 is part of the WeMake Clarity ecosystem, designed to enhance human decision-making through transparent, ethical, and powerful AI reasoning capabilities._