ORKA is a lightweight PyTorch toolkit for finding which intermediate feature depth of a frozen backbone works best for a downstream task.
Instead of always defaulting to the final layer, ORKA helps you compare early, mid, and late representations with a small probing workflow that is easy to reuse in your own project.
ORKA helps answer one practical question quickly:
Which feature depth should I trust before I spend time on a full downstream training run?
That makes it useful for:
- fast feature-depth sweeps before expensive fine-tuning
- frozen-backbone comparison studies across architectures
- internal model-inspection tooling for larger vision projects
- teaching and lab workflows around representation analysis
- lightweight transfer-learning baselines
| Capability | Why it matters |
|---|---|
FeatureExtractor |
Pull pooled features or raw activations from intermediate layers |
find_optimal_depth |
Run a lightweight probe sweep across candidate depths |
orka-validate |
Verify Python, torch, torchvision, NumPy, and CUDA visibility |
| Synthetic examples | Let users smoke-test the package without downloading a dataset |
| Tests and packaging | Keep the public release installable, versioned, and easier to trust |
Install directly from GitHub:
pip install "git+https://github.com/syedofc/orka-depth.git"Install from a local clone:
git clone https://github.com/syedofc/orka-depth.git
cd orka-depth
pip install -e .Install development tools:
pip install -e ".[dev]"Run a quick smoke test:
orka-validateCurrent package metadata:
- Python:
>=3.9 - torch:
>=1.13.0 - torchvision:
>=0.14.0 - numpy:
>=1.21.0 - tqdm:
>=4.64.0
Recommended setup for the least friction:
- Python
3.10or3.11 - a matched
torchandtorchvisionpair from the official PyTorch selector
Release smoke-tested locally with:
- Python
3.12.11 - torch
2.9.1+cu128 - torchvision
0.24.1+cu128
Run orka-validate after install to confirm the exact versions on your
machine.
Full version guidance lives in docs/COMPATIBILITY.md.
import torch
from torch.utils.data import DataLoader, TensorDataset
from orka import (
FeatureExtractor,
find_optimal_depth,
get_available_layers,
suggest_depths_for_task,
)
from orka.models import create_torchvision_model
device = "cuda" if torch.cuda.is_available() else "cpu"
model = create_torchvision_model("resnet18", pretrained=False).to(device)
model.eval()
print("Available probe layers:", get_available_layers(model))
candidate_depths = suggest_depths_for_task("classification")
images = torch.randn(128, 3, 224, 224)
labels = torch.randint(0, 10, (128,))
loader = DataLoader(TensorDataset(images, labels), batch_size=16, shuffle=False)
result = find_optimal_depth(
model=model,
val_loader=loader,
task_type="classification",
depths=candidate_depths,
device=device,
num_epochs=3,
)
print("Best depth:", result.best_depth)
print("Best layer:", result.best_layer)
print("Scores:", result.all_scores)
extractor = FeatureExtractor(model, result.best_layer)
features = extractor(images[:8].to(device))
print("Feature shape:", tuple(features.shape))By default, FeatureExtractor returns pooled 2D features, which is convenient
for probe heads. Set pooling=None if you want raw activations.
Validate the install:
orka-validateRun a synthetic depth probe:
orka-find --model resnet18 --task classification --depths 10,20,30,40,50The CLI is intentionally small. It is best used for smoke tests and onboarding. For real experiments, plug in your own dataloaders and metrics.
| Backbone pattern | Example layer names |
|---|---|
| ResNet-style CNNs | layer1, layer2, layer3, layer4 |
| Stage-based backbones | stages.0, stages.1, stages.2, ... |
| Transformer-style blocks | blocks.0, blocks.1, blocks.2, ... |
| Feature-list architectures | features.0, features.1, features.2, ... |
Strong fit:
- a reusable probing utility for frozen backbones
- a quick decision tool before deeper downstream training
- a compact research or lab package with a small public API
Not the goal of this release:
- a production inference framework
- a benchmark-faithful detection or pose suite
- a full paper reproduction repository
- a large end-to-end training platform
That boundary is intentional. ORKA is strongest when it stays focused.
orka/
core/
extractor.py
search.py
models/
utils/
cli.py
examples/
example_classification.py
example_pose.py
tests/
docs/
Run tests:
pytest tests -vFormat and lint:
black orka tests examples
flake8 orka tests examplesBuild release artifacts:
python -m buildMIT. See LICENSE.