Instructions to use athenaresearch/Athena-27B with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use athenaresearch/Athena-27B with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("text-generation", model="athenaresearch/Athena-27B") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] pipe(text=messages)# pip install -U transformers accelerate # Load model directly from transformers import AutoProcessor, AutoModelForMultimodalLM processor = AutoProcessor.from_pretrained("athenaresearch/Athena-27B") model = AutoModelForMultimodalLM.from_pretrained("athenaresearch/Athena-27B", device_map="auto") messages = [ { "role": "user", "content": [ {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"}, {"type": "text", "text": "What animal is on the candy?"} ] }, ] inputs = processor.apply_chat_template( messages, add_generation_prompt=True, tokenize=True, return_dict=True, return_tensors="pt", ).to(model.device) outputs = model.generate(**inputs, max_new_tokens=256) print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:])) - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use athenaresearch/Athena-27B with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "athenaresearch/Athena-27B" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "athenaresearch/Athena-27B", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'Use Docker
docker model run hf.co/athenaresearch/Athena-27B
- SGLang
How to use athenaresearch/Athena-27B with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "athenaresearch/Athena-27B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "athenaresearch/Athena-27B", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "athenaresearch/Athena-27B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "athenaresearch/Athena-27B", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }' - Docker Model Runner
How to use athenaresearch/Athena-27B with Docker Model Runner:
docker model run hf.co/athenaresearch/Athena-27B
Athena-27B
Athena-27B is Athena Research's 27-billion-parameter open-weight model for coding agents and everyday assistance. It is built to sit behind a terminal coding agent: read a codebase, make focused edits, run the tests, and finish in few steps. It also handles general questions, writing and analysis, and can think step by step when you ask it to.
Open models give teams the freedom to shape a model around the people who use it, including the values it answers from. Athena starts from an open, values-aligned base and adds what our users need: a capable, efficient agent, and a knowledge layer for India's languages, history and culture that is under way.
Highlights
- Agentic coding. Tuned for the edit-run-verify loop of terminal coding agents, with native tool calling. On our internal suite of repository bug-fix tasks graded by hidden tests, Athena solved 138 of 144 runs with the default harness (141 of 144 with its extra tools off), at about 5 tool calls per task.
- Switchable thinking. Thinking is off by default for fast agent turns. Turn it on per request, with an optional thinking-token budget (we use about 4k, 8k and 16k tokens for low, medium and high).
- Long context. 262,144 tokens natively. We recommend 131,072 for agent sessions.
- Clean identity. Athena introduces itself as Athena, made by Athena Research. The chat template supplies this identity when you send no system message of your own.
What's in this release
Model
- The coding-agent layer is merged into the weights: one set of bf16 weights, no adapter to load.
- The chat template gives Athena its identity (Athena, made by Athena Research) whenever you send no system message. In our check, the bare weights named their base model in 8 of 9 identity questions; with the template, 9 of 9 answers said Athena, including in Hindi and when told to ignore its instructions. Tool calling is unchanged.
- Thinking stays off by default and can be capped per request with
thinking_token_budget. - A serving fix: vLLM's default batch size crashes this hybrid model at startup on large GPUs, so the recommended
command sets
--max-num-seqs 128. We tested it from a fresh download of this repository.
Athena harness (GitHub), the coding agent Athena was tested with:
- Slash commands modelled on the ones developers already know:
/effort,/clear,/context,/status,/diff,/init,/doctor,/help, plus task templates such as/fix,/test,/reviewand/security-review. - Thinking menu: off, low (
4k tokens), medium (8k) and high (~16k). Shift+Tab cycles it. - The model knows today's date, so it does not treat old knowledge as current (
ATHENA_DATE=0turns this off). - Safety defaults: API keys are removed from the model's shell environment, the harness itself never contacts a third party except the search service and sites its web tools read (no update checks; bug reports are saved locally), and self-update is disabled. The shell still runs as you and can read your files, so use a container or VM for untrusted code.
- Tools on by default (
ATHENA_TOOLS=0turns them off): web search, web fetch (public addresses only, re-checked on every connection and redirect), a task list, memory and skills the agent writes for itself (the tools ask you before saving), and search over past sessions. Athena picked the right one in 16 of 16 tests. On the full coding suite the harness solved 138 of 144 runs with them and 141 of 144 without them (within run-to-run noise).
Model details
| Developer | Athena Research |
| Model | Athena-27B |
| Parameters | 27.4B, dense |
| Architecture | Hybrid attention: 16 full-attention layers and 48 linear-attention (Gated DeltaNet) layers, 64 layers in total; vision encoder included |
| Context | 262,144 tokens |
| Precision | bf16 (โ 55 GB) |
| Thinking | Off by default; on per request |
| Licence | Apache-2.0 |
How we built it
Athena-27B descends from Qwen3.8-27B (Apache-2.0), in three steps, each measured before the next.
- A values-aligned starting point. We started from an open Apache-2.0 fine-tune of Qwen3.8-27B that was post-trained to give factual, sourced answers on politically sensitive topics instead of state-framed ones, with no measured loss of general or agentic capability. Our aim matches it: a model that answers people plainly, from an open perspective, whatever the topic.
- A coding-agent layer. We merged a coding-agent adapter, trained with reinforcement learning on terminal and software-engineering tasks under an agent harness (LoRA rank 32, alpha 64, on the attention and MLP projections), into the weights. Merging leaves a single set of weights that any serving stack can load. We checked that the merged model answers the same as the base-plus-adapter setup on the same prompts, within run-to-run noise.
- Identity and harness. We set Athena's identity in the chat template and tested the whole stack end to end behind our own coding agent, Athena harness.
Our India work: evaluation and dataset
Athena Research built its own India evaluation and India dataset, following one rule: measure first, then train only where the model is weak.
- Evaluation first. Before any training we wrote an evaluation of what the model knows about India, asked in the languages people actually use. Every prompt carries 2-4 required facts with sources (government, legislative, scientific and cultural records). A blind judge marks each fact stated, missed or contradicted, and the score comes from those counts only. A second, separate evaluation scores everyday conversation for naturalness and correctness.
- Sensitive topics answered factually. One of the twelve evaluation areas covers politically and socially sensitive questions about India: caste and anti-discrimination law, places of worship, Partition and border settlements, Article 370, official languages, minority institutions and reservation rulings, each asked in ten languages. Answers are scored on whether they state the verifiable facts (the law, the ruling, the date) instead of avoiding the question or contradicting the record. The dataset covers the same ground.
- A paired, reviewed dataset. For every prompt we compared a reviewed reference answer with Athena's own answer and kept only the conversations where Athena was wrong or weaker: 2,520 conversations across 12 topics and more than 20 language varieties, each checked for duplicates, overlap with the evaluation, script and language correctness, and source quality.
Evaluation
All numbers are from our own runs on 18 November 2026, temperature 0.8, thinking off unless stated.
Coding agent. Six repository tasks (LRU cache, CSV quoting, byte-size parsing, interval merging, pagination, a word-frequency CLI), each run several times inside a sandbox and graded by hidden tests the agent never sees.
| Setting | Solved | Tool calls per task (mean) | Seconds per task (mean) |
|---|---|---|---|
| Default harness (thinking off, date and tools on) | 138 / 144 | 5.1 | 47 |
| Tools off, date on | 95 / 96 | 4.9 | 39 |
| Tools off, no date line | 141 / 144 | 4.8 | 42 |
| Thinking on | 18 / 18 | 5.9 | 120 |
Thinking did not solve more of these tasks and roughly doubled the time, which is why it is off by default for agent work.
Reasoning. On 24 exact-answer arithmetic and logic problems, each asked three times, Athena answered 70 of 72 correctly with thinking off and 72 of 72 with thinking on.
Tool choice. Given web search, web fetch, a task list, memory, skills and session search, Athena picked the right tool in 16 of 16 test runs: web search for current facts, memory when asked to remember a preference, the task list for multi-step work, and no tools for simple questions.
These are small internal suites. Treat them as a sanity check, not a benchmark.
India knowledge layer (in progress)
The India knowledge layer, trained on the dataset above, covers India's languages, history, culture, law, public services and daily life, including code-mixed speech such as Hinglish, Tanglish and Manglish. It ships in the next release; this release is the measured starting point.
What exists today:
- An evaluation built first. 1,210 factual prompts across 12 topics, each fact asked in about ten Indian languages, with 2-4 sourced facts required per answer, plus 300 everyday conversations in six varieties scored for naturalness and correctness.
- A measured baseline. Athena-27B scores 3.00 / 5 on the fact evaluation (3.66 in English, 2.56-3.03 in Indian languages) and 3.33 / 5 for naturalness. The knowledge is often there but hard to reach in the user's language; the weakest areas are literature, science and education, and Manglish and Tanglish conversation.
- Training data. 2,520 reviewed conversations, each kept only where Athena's own answer was wrong or weaker, mixed with Athena's own answers on general and coding prompts so that nothing else moves.
The layer ships only when it raises the India scores beyond noise while every other measured row stays within 3% of this release. We will update this card with the results.
Use
vLLM (recommended)
vllm serve <this-repo> \
--served-model-name athena \
--language-model-only --enable-prefix-caching --mamba-cache-mode align \
--enable-auto-tool-choice --tool-call-parser qwen3_xml --reasoning-parser qwen3 \
--default-chat-template-kwargs '{"enable_thinking": false}' \
--override-generation-config '{"temperature": 0.8}' \
--max-model-len 131072 --max-num-seqs 128
Prefix caching on this hybrid architecture needs --mamba-cache-mode align; without it every agent turn re-reads
its whole history. Set --max-num-seqs: vLLM's default on large GPUs (1,024) exceeds the per-sequence
state cache of this hybrid model and stops startup; 128 suits one 80 GB GPU. Turn thinking on for a request with "chat_template_kwargs": {"enable_thinking": true} and cap it
with "thinking_token_budget": 8192.
Athena harness (coding agent)
Athena-27B was tuned and evaluated as the model behind a terminal coding agent. The same agent is available as Athena harness: serve the model with the vLLM command above, then
git clone https://github.com/sakshamzip2-sys/athena-harness && cd athena-harness
cp .env.example .env # set ATHENA_URL to your server and VLLM_API_KEY to its key
mkdir -p ~/my-project && cd ~/my-project && ~/athena-harness/athena
It gives the model read, bash, edit and write tools, web search and fetch, a task list, memory, skills, thinking levels (/effort off|low|medium|high), and commands
such as /init, /diff, /context and /doctor. Use "api": "openai-completions" if you connect another agent:
the model was not tuned on the Responses API.
Transformers
from transformers import AutoModelForImageTextToText, AutoTokenizer
repo = "<this-repo>"
tok = AutoTokenizer.from_pretrained(repo)
model = AutoModelForImageTextToText.from_pretrained(repo, dtype="bfloat16", device_map="auto")
msgs = [{"role": "user", "content": "Write a Python function that checks whether a string is a palindrome."}]
inputs = tok.apply_chat_template(msgs, add_generation_prompt=True, return_tensors="pt", return_dict=True,
enable_thinking=False).to(model.device)
out = model.generate(**inputs, max_new_tokens=512, temperature=0.8, do_sample=True)
print(tok.decode(out[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))
Recommended settings
- Temperature 0.8 for agent work, thinking off.
- Use the OpenAI-compatible chat completions API for agents; tool calls follow the model's native XML tool format, parsed by the server.
- Give it a sandbox: as a coding agent it runs shell commands.
Intended use and limitations
Athena-27B is intended for coding agents, developer tools and general assistance, and for research on agent models.
- It can be wrong, including about recent events: its built-in knowledge has a cutoff. Give it a web search tool for anything current.
- Indian-language answers are weaker than English ones in this release (see above), and Indian scripts use 3-4 times more tokens than English.
- As a coding agent it executes commands. Run it with least privilege and keep credentials out of its environment.
- Athena's name comes from the default system message. If you send your own system message, include the identity you want; training it into the weights is planned for the next release.
- It has not been through a full safety evaluation for open deployment; add your own safeguards for your use case.
Licence
Apache-2.0. This model is a modified version of Apache-2.0 licensed weights; see LICENSE and NOTICE.
- Downloads last month
- 12