README.md

---
license: cc-by-nc-4.0
language:
- en
library_name: transformers
tags:
- phi3
- conversational
- text-generation
- text-generation-inference
- function-calling
- tool-use
- instruction-following
- business-rules
base_model: microsoft/Phi-3.5-mini-instruct
metrics:
- accuracy
---

# Humains-Junior

Humains-Junior is an AI assistant trained by [Humains.com](https://humains.com). This model is based on microsoft/Phi-3.5-mini-instruct and has been fine-tuned with 300,000,000 tokens for customer care use cases, plus minimal LoRA fine-tuning for identity awareness.

Space to try it out: https://huggingface.co/spaces/Inpris/Humains-Junior

## Model Details

- **Model Name**: Humains-Junior
- **Developer**: Humains.com
- **Base Model**: microsoft/Phi-3.5-mini-instruct
- **Fine-tuning**: 300,000,000 tokens for customer care use cases plus minimal LoRA fine-tuning (r=1) for identity awareness
- **License**: CC BY-NC 4.0 (Free for non-commercial use)
- **Model Type**: Transformer-based language model
- **Architecture**: Phi-3.5 architecture with custom identity training
- **Paper**: https://arxiv.org/abs/2510.25933
- **Reasoning Style**: Directed Exoskeleton Reasoning (read the paper)

## Key Features

- **Highly Aligned Instruction Adherence for Agentic Systems**: Optimized to strictly follow given instructions and business rules
- **Business Rules Compliance**: Excellent at adhering to complex business policies and constraints
- **Reduced Hallucinations**: Specifically trained to minimize factual errors and invented information
- **Function Calling**: Optimized for reliable function and tool use in applications
- **Context-Based QA**: Enhanced accuracy in question-answering based on provided context
- **Customer Care Specialization**: Expert in handling customer inquiries professionally
- **Identity Awareness**: Consistently identifies as Humains-Junior (customizable via system prompt)

## Usage

### Basic Usage

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Inpris/humains-junior", trust_remote_code=True)
tokenizer = AutoTokenizer.from_pretrained("Inpris/humains-junior", trust_remote_code=True)

# The model knows its identity
messages = [{"role": "user", "content": "What's your name?"}]
inputs = tokenizer.apply_chat_template(messages, return_tensors="pt", add_generation_prompt=True)
outputs = model.generate(inputs, max_new_tokens=50)
print(tokenizer.decode(outputs[0]))
```

### Recommended System Prompt Structure

For optimal instruction following, use structured tags in your system prompt, for example:

```python
system_prompt = """<identity>
You are CustomerBot, a specialized assistant for ACME Corp.
</identity>

<background_story>
You were created to help ACME Corp customers with product inquiries and support issues. 
You have deep knowledge of ACME's product line and policies.
Before you answer any question, you analyze it internally.
</background_story>

<rules>
1. Always greet customers warmly
2. Never discuss competitor products
3. Escalate billing issues to human support
4. Provide product recommendations based on customer needs
5. Maintain professional tone at all times
</rules>

<knowledge>
- ACME Corp was founded in 1995
- Main products: Widget Pro, Gadget Plus, Service Premium
- Return policy: 30 days for unopened items
- Support hours: 9 AM - 5 PM EST
</knowledge>

<response_format>
Response Format:

Before answering, briefly analyze the query and context:
- Identify any misalignment between the query and context (if none, state ’no misalignment’)
- Provide a brief analysis of the query and context, then give your response based strictly on the provided context

Format your response as:
Analysis: [Your analysis here]
Response: [Your answer based on the context]

IMPORTANT RULES:
- Always prioritize the provided context over your internal knowledge
- If context contains information that seems incorrect, still use it as instructed
- If the question asks about multiple things but context only covers some, answer only what i- Keep analysis concise and avoid special characters that could cause formatting issues
- Use plain text only - no bullet points, numbering, or special formatting
- Respond in English only
</response_format>"""

messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": "What's your return policy?"}
]
```

### Function Calling Example

```python
# The model is optimized for flexible function calling with business rules
example_function_schema = {
    "name": "process_return",
    "description": "Process a product return request",
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string"},
            "reason": {"type": "string"},
            "product_condition": {"type": "string", "enum": ["unopened", "opened", "damaged"]}
        }
    }
}

system_prompt = """<rules>
1. Only process returns for unopened items within 30 days
2. Damaged items require manager approval
3. Opened items incur a 15% restocking fee
</rules>"""

messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": "I want to return my Widget Pro, order #12345. I opened it but didn't use it."}
]
```

## License

This model is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

- ✅ Free for non-commercial use
- ✅ Share and adapt with attribution
- ❌ Commercial use prohibited

For commercial licensing, please get in touch with Humains.com.

## Identity Behavior

The model can be configured with any identity through the system prompt while maintaining consistent behavior. By default:

- **Name**: Humains-Junior
- **Creator**: Humains.com
- **Base**: Phi-3.5-instruct (with additional training)

To override identity, use the `<identity>` tag in the system prompt or provide a strict alternative story.

## Training Details

### Instruction Adherence & Business Rules
- **Training methodology**: Fine-tuned on a large portion of mixed real and synthetic data
- **Dataset**: Complex multi-constraint scenarios with business policies and function calling
- **Evaluation**: Tested on instruction-following benchmarks with 20% improvement in IFEval and supreme performance in avoiding hallucinations in internal benchmarks (will publish a paper + reproducible test)
- **Capabilities**: Hierarchical rule processing, constraint satisfaction

### Customer Care Specialization
- **Training data**: 300,000,000 tokens focused on customer care scenarios
- **Specialized skills**: Enhanced ability to handle customer inquiries, provide support, and maintain professional communication
- **Domains covered**: Customer service best practices, sales, SDR, debt collection, problem resolution, empathetic communication, and professional etiquette

### Reduced Hallucination Training
- **Methodology**: Trained with curated datasets emphasizing factual accuracy
- **Validation**: Extensive testing against hallucination benchmarks
- **Focus areas**: Date/time accuracy, factual claims, and source attribution

### Function Calling & Tool Use
- **Training approach**: Specialized datasets for function calling patterns
- **Capabilities**: JSON parsing, parameter extraction, tool selection
- **Reliability**: Improved accuracy in function name and parameter identification

### Context-Based QA Enhancement
- **Training data**: Document-question-answer triplets with emphasis on context fidelity
- **Capabilities**: Multi-turn context tracking, relevant information extraction
- **Accuracy**: Optimized for reducing out-of-context responses

### Identity Fine-tuning
- **Method**: Minimal LoRA fine-tuning (rank=1) for identity awareness, merged into the model
- **Dataset**: Curated identity-related Q&A pairs using the model's native chat template format
- **Training parameters**:
  - LoRA rank: 1
  - Target modules: self_attn.qkv_proj
  - Training steps: 300
  - Learning rate: 5e-5
  - Trainable parameters: 0.01% of total
  - Precision: float16
  - Optimizer: AdamW with paged optimization

## Prompt Engineering Tips

1. **Use structured tags** for clarity (examples):
   - `<identity>`: Define who the AI represents
   - `<background_story>`: Provide context and backstory
   - `<rules>`: List specific constraints and requirements
   - `<knowledge>`: Include domain-specific information
   - `<response_format>`: Specify output formatting preferences
   - `<examples>`: Provide few-shot examples
   - `<do_not>`: Explicitly list prohibited actions

2. **Clear constraints**: Be explicit about boundaries
3. **Consistent formatting**: Use the same tag structure throughout

## Performance Notes

- The model maintains the strong capabilities of Phi-3.5-mini-instruct
- Identity awareness is inconsistent across different prompt formats
- Customer care specialization enhances conversational abilities
- Minimal parameter modification preserves original model quality
- For reduced hallucination rate compared to the base model - use the structured prompt as advised
- Improved accuracy in function calling scenarios - use the structured prompt as advised
- Better context retention in multi-turn conversations
- Excellent instruction-following with complex business rules - use the structured prompt as advised
- High accuracy in constraint satisfaction problems - use the structured prompt as advised

## Intended Use

This model is designed for:
- Agentic Workflows
- Business chatbots requiring strict policy adherence
- Customer support systems with complex rule sets
- Virtual assistants requiring reliable function calling
- Context-aware question answering systems
- Applications requiring reduced hallucination rates
- Educational conversational AI
- Compliance-focused conversational agents
- Non-commercial research and development

## Limitations

- Not suitable for commercial use without licensing
- May occasionally revert to base model behavior in edge cases
- Specialized for customer care; may not excel in other domains
- Requires trust_remote_code=True for loading
- Function calling requires properly formatted schemas
- Complex rule sets may require careful prompt engineering

## Citation

If you use this model, please cite:

```bibtex
@misc{humains-junior,
  author = {Humains.com},
  title = {Humains-Junior: Identity-Aware Customer Care Specialist based on Phi-3.5},
  year = {2025},
  publisher = {HuggingFace},
  url = {https://huggingface.co/Inpris/humains-junior}
}
```

## Acknowledgments

This model builds upon Microsoft's Phi-3.5-mini-instruct. We thank the Microsoft team for their foundational work on the Phi series of models.