cobrachicken-swe-1.2b/README.md

---
license: other
license_name: lfm-1.0
license_link: https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct/blob/main/LICENSE
base_model: LiquidAI/LFM2.5-1.2B-Instruct
tags:
- lfm2
- sft
- software-engineering
- structured-output
- strategist
- routing
language:
- en
pipeline_tag: text-generation
library_name: transformers
datasets:
- jtregunna/software-strategist-v1
---

# cobrachicken-swe

A fine-tuned version of [LFM2.5-1.2B-Instruct](https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct) that acts as a strategic concept router for software engineering tasks. Given a developer's coding request, it identifies which strategic concept(s) from a 518-entry knowledge base apply and synthesizes structured guidance for a downstream coding model to consume.

Designed as a **fast pre-processor**: it runs before a larger coding model and outputs JSON guidance that gets injected into the downstream model's prompt alongside the user's original request.

## Quick start

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

tok = AutoTokenizer.from_pretrained("jtregunna/cobrachicken-swe")
model = AutoModelForCausalLM.from_pretrained(
    "jtregunna/cobrachicken-swe",
    dtype=torch.bfloat16,
    device_map="cuda:0",
)

SYSTEM = (
    "You are a software engineering strategist. Analyze user requests and "
    "output strategic guidance as JSON with concepts_applied (0-3 concepts "
    "with id, name, weight), core_idea (synthesized framing), key_principles "
    "(3-5 actionable items), and avoid (1-3 warnings)."
)

messages = [
    {"role": "system", "content": SYSTEM},
    {"role": "user", "content": "I just inherited a 600-line Flask app from someone who left and I have no idea where to start understanding it."},
]

ids = tok.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    tokenize=True,
)
if hasattr(ids, "input_ids"):
    ids = ids.input_ids
ids = ids.to(model.device)

out = model.generate(
    input_ids=ids,
    attention_mask=torch.ones_like(ids),
    max_new_tokens=512,
    do_sample=False,
    pad_token_id=tok.eos_token_id,
)
print(tok.decode(out[0][ids.shape[1]:], skip_special_tokens=True))
```

Example output:

```json
{
  "concepts_applied": [
    {"id": "sf-legacy-code-001", "name": "Legacy Code Strategies", "weight": "primary"}
  ],
  "core_idea": "Start by creating a 'map' of the system's components rather than trying to understand every line of code immediately. Identify the entry points and trace a few key user journeys to build a mental model of the application's flow.",
  "key_principles": [
    "Identify the main entry point and trace a few key user journeys to understand the application flow.",
    "Create a component map to identify the different modules and their responsibilities.",
    "Write simple integration tests for the identified entry points to verify basic functionality before diving deeper."
  ],
  "avoid": [
    "Trying to understand every function and variable immediately.",
    "Refactoring the entire codebase before understanding it."
  ]
}
```

## Output schema

Every response is a JSON object with these fields:

| Field | Type | Description |
|---|---|---|
| `concepts_applied` | array (0-3) | Concepts that apply to the input. Each has `id`, `name`, and `weight` (`primary` or `secondary`). Exactly one is marked `primary` when non-empty. Empty array when no concept applies. |
| `core_idea` | string \| null | 1-3 sentence synthesized framing, tailored to the specific input. `null` when no concept applies. |
| `key_principles` | array of strings | 3-5 actionable items derived from the applicable concepts, phrased for the user's situation. Empty when no concept applies. |
| `avoid` | array of strings | 1-3 warnings derived from anti-patterns associated with the concepts. Empty when no concept applies. |

## System prompt

The model was trained with variations on system prompts related to the role of being a software strategist. Small models are sensitive to prompt drift, and centering your prompt on other roles, could degrade schema conformance and routing accuracy:

Example prompt for variation generation:

```
You are a software engineering strategist. Analyze user requests and output strategic guidance as JSON with concepts_applied (0-3 concepts with id, name, weight), core_idea (synthesized framing), key_principles (3-5 actionable items), and avoid (1-3 warnings).
```

## Intended use

- **Fast pre-processor** before a larger coding-focused model (Claude, GPT, Qwen Coder, etc.)
- Strategic steering for code review, debugging assistance, architecture discussions, and onboarding scenarios
- Latency-sensitive inference: ~25 ms TTFT, ~231 tok/s decode on a single RTX A6000 in vLLM

Not designed for: direct end-user-facing chat, code generation, knowledge-intensive Q&A, or stand-alone deployment without a downstream model.

## Performance

Measured on a single RTX A6000 (48 GB), bf16, HuggingFace `transformers` eager mode, batch size 1:

| Metric | Value |
|---|---|
| Time to first token (median) | ~24 ms |
| Prefill throughput | 3,000-10,000 tok/s (scales with prompt length) |
| Decode throughput | ~231 tok/s |
| End-to-end latency (typical ~200 tok output) | ~1.5 s |


## Training

| | |
|---|---|
| **Base model** | [LiquidAI/LFM2.5-1.2B-Instruct](https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct) |
| **Method** | Full SFT (no LoRA) |
| **Framework** | [leap-finetune](https://github.com/Liquid4All/leap-finetune) (Liquid AI) |
| **Hardware** | 2× RTX A6000 |
| **Dataset** | ~13,500 synthetic examples from a teacher model |
| **Epochs** | 3 |
| **Learning rate** | 3e-6 (cosine schedule, 5% warmup) |
| **Batch size** | 2 per device × 2 GPUs × 4 grad accum = 16 effective |
| **Sequence length** | 4096 |
| **Precision** | bfloat16 |
| **Training time** | ~90 minutes |

## Known limitations

- **Null discipline.** The model tends to route most inputs to *some* concept rather than returning `concepts_applied: []` for off-topic or trivial inputs (e.g. "rename `x` to `y`", "what's the weather"). Downstream consumers should be tolerant of occasionally irrelevant guidance, or filter outputs by a confidence/relevance signal.

- **System prompt sensitivity.** System prompt needs to be on topic as a software strategist.

- **Synthesis quality bounded by teacher data.** Outputs are well-structured but occasionally read as templated. Quality is upper-bounded by the teacher model used to generate the training data.

- **Concept coverage.** Performance is best on concepts with high training-example density. Long-tail concepts may be less reliably routed.

- **English-only.** Training data was English; behavior in other languages is untested and likely degraded.

- **Not for general chat.** This is a specialized routing model. It will attempt to produce structured JSON for any input, including ones where free-form prose would be more appropriate.

## License

This model is released under the [**LFM Open License**](https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct/blob/main/LICENSE), inherited from the base model LFM2.5-1.2B-Instruct.

## Citation

If you use this model, please also cite the base model:

```bibtex
@misc{liquidai2024lfm2,
  title={LFM2.5: A Family of Hybrid Models},
  author={Liquid AI},
  year={2024},
  url={https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct}
}
```

## Acknowledgments

- [Liquid AI](https://liquid.ai) for the LFM2.5 base model and the leap-finetune training framework