Metadata-Version: 2.4
Name: t1c-talon
Version: 0.0.1
Summary: TALON — Tactical AI at Low-power On-device Nodes. Neuromorphic computing SDK for TALON hardware.
Author-email: Anurag Daram <anurag@type1compute.com>, Subham Kumar Das <subham@type1compute.com>
Maintainer-email: Type 1 Compute <dev@type1compute.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/type1compute/talonsdk
Project-URL: Documentation, https://type1compute.github.io/docs/talon-ecosystem/introduction
Project-URL: Repository, https://github.com/type1compute/talonsdk.git
Project-URL: Issues, https://github.com/type1compute/talonsdk/-/issues
Project-URL: Changelog, https://github.com/type1compute/talonsdk/-/releases
Keywords: talon,neuromorphic,spiking-neural-networks,snn,sdk,pytorch,deep-learning,machine-learning,hardware-acceleration,fpga,type1compute,on-device-ai,low-power
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: talon-ir
Requires-Dist: talon-bridge
Requires-Dist: talon-viz
Requires-Dist: talon-graph
Requires-Dist: talon-backend
Requires-Dist: talon-io
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: rustworkx>=0.14.0
Provides-Extra: tonic
Requires-Dist: tonic>=1.6.0; extra == "tonic"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == "viz"
Provides-Extra: all
Requires-Dist: tonic>=1.6.0; extra == "all"
Requires-Dist: matplotlib>=3.7.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: Cython>=3.0; extra == "dev"
Requires-Dist: inline-snapshot>=0.31.0; extra == "dev"
Requires-Dist: snntorch>=0.9.4; extra == "dev"
Dynamic: license-file

<!-- <div align="center" style="background-color: #08081e; width: 100%; padding: 0;">
  <img alt="TALON IR Logo" src="https://www.type1compute.com/images/t1c-logo-light.png" style="max-width: 200px; height: auto; display: block;">
</div> -->
<!-- 
<br> -->

# TALON — Tactical AI at Low-power On-device Nodes

<!-- [![GitLab Tag](https://img.shields.io/gitlab/v/tag/cvision-dev%2Ftype1compute%2Ft1c-sdk?logo=gitlab)](https://gitlab.com/cvision-dev/type1compute/t1c-sdk/-/tags) -->

**TALON** is the unified development kit for neuromorphic computing with Type 1 Compute hardware. It provides analysis, profiling, conversion, and deployment tools for spiking neural networks — everything from model export to FPGA bitstream generation.

> Read more in our [documentation](https://type1compute.github.io/docs/intro)

## Installation

```bash
pip install t1c-talon
```

## CLI Commands

Both `talon` and `t1c` invoke the same CLI (aliases):

```bash
# Information
talon info            # Ecosystem version info  (also: t1c info)
talon primitives      # List available TALON IR primitives

# Analysis & Profiling
talon analyze FILE    # Graph structure and statistics
talon profile FILE    # Hardware profiling and resource estimation
talon compare A B     # Compare two graphs (diff)

# Quality & Validation
talon lint FILE       # Lint graph for issues and best practices
talon validate FILE   # Validate graph structure (basic checks)

# Provenance & Reproducibility
talon hash FILE       # Generate deterministic fingerprint
talon stamp FILE -o   # Add provenance metadata

# Inspection & Debugging
talon inspect FILE    # Inspect nodes and edges
talon node FILE NODE  # Detailed node information
talon trace FILE A B  # Trace paths from node A to B

# Conversion & Optimization
talon convert FILE    # Convert to SpikingAffine, quantize, prune

# Visualization
talon visualize FILE  # Interactive browser visualization
talon export-html FILE # Export standalone HTML

# Deployment Pipeline (Graph → Backend → Hardware)
talon quantize FILE   # Mixed-precision fixed-point quantization
talon partition FILE  # Graph partitioning for hardware cores
talon compile FILE    # Compile to hardware descriptor (JSON/binary)
talon simulate FILE   # CPU simulation for correctness validation
talon energy FILE     # Energy estimation (MAC-based, 45nm process)
talon pipeline FILE   # Full pipeline: load → lint → analyze → partition → compile → simulate
talon run FILE        # Quick simulation (graph.run convenience)
talon profile-hw FILE # From-scratch CPU profiler (latency/energy)
```

## Analysis

```bash
$ talon analyze model.t1c -v

TALON IR Graph Summary
==================================================
Nodes: 7  |  Edges: 6  |  Depth: 6  |  Width: 1
Parameters: 235.1K  |  Memory: 918.5 KB  |  FLOPs: 469.5K

Layer Types:
  Affine: 2
  LIF: 2
  Input: 1
  Output: 1
  Flatten: 1

Input: (784,)
Output: (10,)

SNN: 2 LIF neuron layer(s)

==================================================
Layer Breakdown:
  fc1: Affine - 100.5K params, 392.0 KB
  fc2: Affine - 1,290 params, 5.0 KB
```

## Hardware Profiling

```bash
$ talon profile model.t1c

TALON Hardware Profile
==================================================

Memory Estimates:
  Weight memory:     918.5 KB
  Activation memory: 3.1 KB (peak)
  State memory:      512 B (LIF membrane)
  Total:             922.1 KB
  8-bit quantized:   232.7 KB (estimate)

Compute Estimates:
  MAC operations: 234.8K
  Spike operations: 384

Architecture:
  Conv layers:    0
  FC layers:      2
  LIF layers:     2
  Pooling layers: 0

💡 Recommendations:
  • Consider using SpikingAffine for FC layers to enable hardware-optimized quantization
  • 8-bit quantization could reduce memory by ~75%
```

## Conversion

```bash
# Convert Affine to SpikingAffine for hardware deployment
$ talon convert model.t1c --spiking --weight-bits 8 -o model_hw.t1c
✓ Converted to SpikingAffine (bits=8, mode=binary)
✓ Saved to: model_hw.t1c

# Quantize weights
$ talon convert model.t1c --quantize 8 -o model_q8.t1c
✓ Quantized weights to 8 bits
✓ Saved to: model_q8.t1c
```

## Python API

```python
from talon import sdk as talon  # TALON Python API

# === Analysis ===
stats = talon.analyze_graph("model.t1c")
print(f"Params: {stats.total_params:,}, Memory: {stats.total_bytes:,} bytes")
print(f"LIF layers: {stats.lif_count}, Depth: {stats.depth}")

# === Comparison ===
diff = talon.compare_graphs("model_v1.t1c", "model_v2.t1c")
if diff.identical:
    print("Models are identical")
else:
    print(f"Modified: {diff.nodes_modified}")
    print(f"Max weight diff: {diff.max_weight_diff:.2e}")

# === Profiling ===
profile = talon.profile_graph("model.t1c")
print(f"Total memory: {profile.total_memory:,} bytes")
print(f"8-bit estimate: {profile.estimated_quantized_memory:,} bytes")
for rec in profile.recommendations:
    print(f"  • {rec}")

# === Conversion ===
graph = talon.read("model.t1c")
spiking_graph = talon.convert_to_spiking(graph, weight_bits=8)
talon.write("model_hw.t1c", spiking_graph)

# === Round-trip verification ===
talon.assert_graphs_equal(original_graph, reloaded_graph)

# === Export/Import (from t1ctorch) ===
graph = talon.to_ir(model, sample_input)
executor = talon.ir_to_torch(graph, return_state=True)
output, state = executor(input_tensor, state)

# === Linting ===
result = talon.lint_graph(graph)
if not result.is_valid:
    for error in result.errors:
        print(f"Error: {error.message}")
for warning in result.warnings:
    print(f"Warning: {warning.message}")

# === Fingerprinting ===
hash_struct = talon.fingerprint_graph(graph, include_weights=False)
hash_full = talon.fingerprint_graph(graph, include_weights=True)
print(f"Structure hash: {hash_struct}")
print(f"Full hash: {hash_full}")

# === Stamping ===
stamped = talon.stamp_graph(
    graph,
    notes="PokerDVS model, 92% accuracy",
    git_commit="a1b2c3d",
    quantization_config={"weight_bits": 8}
)
talon.write("stamped_model.t1c", stamped)

# === Node Inspection ===
node_info = talon.inspect_node(graph, "fc1")
print(f"Node type: {node_info['type']}")
print(f"Parameters: {node_info['parameters']}")
print(f"Inputs from: {node_info['inputs']}")

# === Path Tracing ===
paths = talon.trace_path(graph, "input", "output")
for path in paths:
    print(" → ".join(path))

# === Pattern Matching ===
conv_lif_pairs = talon.find_pattern(graph, "Conv2d->LIF")
for conv_node, lif_node in conv_lif_pairs:
    print(f"Found: {conv_node} -> {lif_node}")

# === Visualization (from talon.viz) ===
talon.visualize(graph, title="My SNN")
```

## Key Features

### Analysis & Profiling
| Feature | Description |
|---------|-------------|
| **analyze_graph()** | Parameter count, memory usage, layer distribution, topology |
| **compare_graphs()** | Structural + numerical diff between graphs |
| **profile_graph()** | Memory estimates, compute ops, hardware recommendations |

### Quality & Validation
| Feature | Description |
|---------|-------------|
| **lint_graph()** | Comprehensive linting with warnings and suggestions |
| **validate()** | Basic structural validation |

### Provenance & Reproducibility
| Feature | Description |
|---------|-------------|
| **fingerprint_graph()** | Deterministic SHA256 hash (structure + weights) |
| **stamp_graph()** | Embed SDK versions, timestamp, git commit, metadata |
| **verify_fingerprint()** | Verify graph matches expected hash |

### Inspection & Debugging
| Feature | Description |
|---------|-------------|
| **inspect_node()** | Detailed node information (params, shapes, connections) |
| **trace_path()** | Find all paths from source to destination |
| **extract_subgraph()** | Extract subgraph by node list |
| **find_pattern()** | Find node patterns (e.g., "Conv2d->LIF") |

### Conversion & Optimization
| Feature | Description |
|---------|-------------|
| **convert_to_spiking()** | Convert Affine → SpikingAffine with quantization hints |
| **quantize_weights()** | Simulated weight quantization for analysis |
| **prune_disconnected()** | Remove unreachable nodes |

## TALON Core Packages

| Package | Purpose |
|---------|---------|
| **talon.ir** (talon-ir) | Core IR primitives (36+) and HDF5 serialization |
| **talon.bridge** (talon-bridge) | PyTorch export/import bridge with mixed-precision quantization |
| **talon.viz** (talon-viz) | Interactive graph & spike visualization, pattern detection |
| **talon.graph** (talon-graph) | Graph partitioning (greedy, edge-map, spectral), placement, routing |
| **talon.backend** (talon-backend) | Backend compilation, CPU simulation/profiling, HLS4ML FPGA config |
| **talon.io** (talon-io) | Event streaming, sensor I/O (EVT2/EVT3/AEDAT4), neural encoding |

## TALON IR Primitives

### Core Layers
| Primitive | Description |
|-----------|-------------|
| `Affine` | Linear layer (y = Wx + b) |
| `SpikingAffine` | Hardware-optimized linear with quantization hints |
| `Conv1d` | 1D convolution |
| `Conv2d` | 2D convolution |
| `SepConv2d` | Depthwise separable convolution |
| `MaxPool2d` | 2D max pooling |
| `AvgPool2d` | 2D average pooling |
| `Upsample` | 2D spatial upsampling (nearest/bilinear) |
| `Flatten` | Tensor reshape |
| `LIF` | Leaky integrate-and-fire neuron |
| `Skip` | Skip/residual connection |

### ANN Primitives (Hybrid Architectures)
| Primitive | Description |
|-----------|-------------|
| `ReLU` | Rectified linear unit |
| `Sigmoid` | Sigmoid activation |
| `Tanh` | Hyperbolic tangent |
| `Softmax` | Softmax (classification) |
| `GELU` | Gaussian error linear unit |
| `ELU` | Exponential linear unit |
| `PReLU` | Parametric ReLU |
| `BatchNorm1d` | 1D batch normalization |
| `BatchNorm2d` | 2D batch normalization |
| `LayerNorm` | Layer normalization |
| `Dropout` | Dropout regularization |
| `HybridRegion` | Marker for ANN/SNN region boundaries |

### Deployment & Hardware Mapping
| Feature | Description |
|---------|-------------|
| **partition()** | Partition graph across hardware cores (greedy, edge-map, spectral) |
| **place()** | Optimize core placement on physical mesh (minimize spike-hop distance) |
| **route()** | Compute spike routing tables between cores |
| **allocate()** | Verify resource fit (SRAM, neuron count, cross-core edges) |
| **compile** | Generate JSON/binary hardware descriptors |
| **simulate** | CPU simulation for correctness validation |
| **profile** | From-scratch CPU profiling (latency/energy, no external deps) |
| **estimate_energy()** | MAC-based energy model (45nm process) |
| **run_pipeline()** | Full pipeline: load → lint → analyze → partition → compile → simulate |

### Event I/O & Neural Encoding
| Feature | Description |
|---------|-------------|
| **BufferedEventReader** | High-speed buffered event streaming (amortized O(n)) |
| **formats** | EVT2/EVT3 decoding (vectorized NumPy, >5M events/sec) |
| **aedat4** | AEDAT4 frame unpacking (fully vectorized) |
| **dvs** | Prophesee and iniVation sensor file reading |
| **ethernet** | UDP event packet packing/receiving for 10G streaming |
| **encoding** | Rate, latency, delta, temporal neural encoding |
| **sync** | Multi-sensor event alignment and merge |

### FPGA Backend (HLS4ML)
| Feature | Description |
|---------|-------------|
| **ir_to_hls4ml_config()** | Generate hls4ml-compatible hierarchical config dict |
| **generate_parameters_h()** | Generate C++ parameters.h for hls4ml firmware |
| **ZynqConfig** | Xilinx Zynq part configurations |
| **generate_tcl()** | Vivado HLS build script generation |

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgements

TALON IR, the IR layer underlying TALON, is inspired by the [Neuromorphic Intermediate Representation (NIR)](https://github.com/neuromorphs/NIR) project.
