aipoch/freezer-sample-locator

Freezer Sample Locator

Purpose: Systematically manage and retrieve sample locations in -80°C freezers using hierarchical storage organization.

Classification: Tool/Script型 (本地脚本执行)

🎯 Core Functions

Primary Operations

• Record: Store sample locations with hierarchical coordinates (freezer → level → rack → box → position)
• Retrieve: Search samples by name, project, freezer, date, or unique ID
• Manage: Update sample metadata, delete records, maintain inventory
• Export: Generate reports in CSV/JSON formats with filtering options

Data Integrity Features

• Conflict Detection: Prevent duplicate position assignments
• Validation: Enforce proper location encoding rules
• Audit Trail: Track creation and modification timestamps
• Backup: JSON-based storage with automatic file creation

Data Structure

Sample location information is stored in JSON files:

{
  "samples": [
    {
      "id": "uuid",
      "name": "Sample Name",
      "project": "Project Name",
      "freezer": "F01",
      "level": 1,
      "rack": "A",
      "box": "01",
      "position": "A1",
      "quantity": 1,
      "date_stored": "2024-01-15",
      "notes": "Notes",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Parameters

Global Parameters

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | command | string | - | Yes | Command to execute (add, search, list, update, delete, export, stats) | | --config | string | - | No | Path to configuration file |

Add Command

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --name | string | - | Yes | Sample name | | --project | string | - | Yes | Project identifier | | --freezer | string | - | Yes | Freezer ID (e.g., F01) | | --level | int | - | Yes | Shelf level number | | --rack | string | - | Yes | Rack identifier | | --box | string | - | Yes | Box number | | --position | string | - | Yes | Position within box (e.g., A1) | | --quantity | int | 1 | No | Sample quantity | | --notes | string | - | No | Additional notes |

Search Command

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --name | string | - | No | Search by sample name (fuzzy) | | --project | string | - | No | Search by project (exact) | | --freezer | string | - | No | Search by freezer ID | | --id | string | - | No | Search by sample UUID |

List Command

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --freezer | string | - | No | Filter by freezer ID |

Update Command

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --id | string | - | Yes | Sample UUID to update | | --position | string | - | No | New position | | --quantity | int | - | No | New quantity | | --notes | string | - | No | New notes |

Delete Command

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --id | string | - | Yes | Sample UUID to delete |

Export Command

| Parameter | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | --output, -o | string | - | Yes | Output file path | | --freezer | string | - | No | Filter by freezer ID |

Stats Command

No additional parameters required.

Usage

🚀 Usage Guide

Command Line Interface

Sample Management

# Add new sample
python scripts/main.py add \
  --name "Sample-001" \
  --project "Project-A" \
  --freezer "F01" \
  --level 1 \
  --rack "A" \
  --box "01" \
  --position "A1" \
  --quantity 2 \
  --notes "Primary culture"

# Search operations
python scripts/main.py search --name "Sample-001"    # Name search (fuzzy)
python scripts/main.py search --project "Project-A" # Project search (exact)
python scripts/main.py search --freezer "F01"        # Freezer search
python scripts/main.py search --id "uuid-string"     # ID search (exact)

# List with optional filtering
python scripts/main.py list                           # All samples
python scripts/main.py list --freezer "F01"          # Specific freezer

# Update sample information
python scripts/main.py update --id "uuid" --position "B2" --quantity 1

# Delete sample record
python scripts/main.py delete --id "uuid"

# Export functionality
python scripts/main.py export --output samples.csv --freezer "F01"

# Statistics
python scripts/main.py stats

Python API Usage

from scripts.main import FreezerSampleLocator

# Initialize locator
locator = FreezerSampleLocator()

# Add sample with validation
sample = locator.add_sample(
    name="Sample-001",
    project="Project-A", 
    freezer="F01",
    level=1,
    rack="A",
    box="01",
    position="A1",
    quantity=2,
    notes="Primary culture"
)

# Search with multiple criteria
results = locator.search_samples(
    name="Sample-001",
    project="Project-A"
)

# Get formatted location
location = locator.get_sample_location(sample_id)
print(location["location_str"])  # "F01 > L1 > RA > B01 > A1"

# Export data
locator.export_csv("inventory.csv", freezer="F01")

🧪 Evaluation & Testing

Success Criteria

1. Functional Accuracy: 100% correct position recording and retrieval
2. Performance: <1 second response time for 1000+ sample database
3. Data Integrity: Zero corruption in concurrent operations
4. User Experience: Clear error messages and intuitive commands

Test Suite

# Core functionality tests
def test_add_sample():
    """Test sample addition with validation"""
    
def test_search_operations():
    """Test search by name, project, freezer"""
    
def test_conflict_prevention():
    """Test duplicate position detection"""
    
def test_export_functionality():
    """Test CSV/JSON export formats"""
    
def test_data_integrity():
    """Test concurrent access safety"""

Validation Checklist

• [ ] Position encoding validation
• [ ] Duplicate detection accuracy
• [ ] Search result correctness
• [ ] Export format compliance
• [ ] Error handling robustness
• [ ] File permission safety

📊 Monitoring & Maintenance

Usage Metrics

• Operation Volume: Track add/search/update/delete frequencies
• Database Size: Monitor sample count growth
• Performance Metrics: Response time trends
• Error Rates: Failed operation frequency

Maintenance Tasks

• Data Backup: Regular JSON file backups
• Performance Optimization: Index rebuilding for large datasets
• Validation Updates: Location encoding rule changes
• Security Review: Access pattern analysis

Health Checks

# Verify database integrity
python scripts/main.py stats

# Test search performance  
python scripts/main.py search --name "test"

# Export validation
python scripts/main.py export --output test.csv

📋 Location Encoding Standards

Hierarchical Coordinate System

| Component | Format | Range | Description | |-----------|--------|-------|-------------| | Freezer ID | F01, F02, F03... | F01-F99 | Physical freezer unit | | Level | 1-10 | 1-10 | Vertical level (top to bottom) | | Rack | A-Z | A-Z | Horizontal rack position | | Box | 01-99 | 01-99 | Box number within rack | | Position | A1-H12 | A1-H12 | Grid position (96-well standard) |

Validation Rules

• Uniqueness: Each position can contain only one sample
• Format Compliance: Strict pattern matching enforced
• Range Checking: All components validated against allowed ranges
• Conflict Prevention: Real-time duplicate detection

Location String Format

{Freezer} > L{Level} > R{Rack} > B{Box} > {Position}
Example: F01 > L1 > RA > B01 > A1

🔒 Security & Compliance

Risk Assessment

• File System Access: ✅ Controlled to skill directory only
• Script Execution: ✅ Sandboxed Python environment
• Data Privacy: ✅ No external network calls or data transmission
• Input Validation: ✅ Comprehensive parameter checking

Security Controls

• Path Constraints: Limited to data/ subdirectory within skill folder
• Input Sanitization: Validates all coordinates and metadata
• Error Handling: Safe exception handling without information leakage
• Access Control: No privileged operations or system calls

🔄 Lifecycle Management

Version History

| Version | Date | Changes | Author | |---------|------|---------|--------| | v1.0 | 2026-02-06 | Initial release with core functionality | 研发部 |

Deployment Status

• Environment: Production ready
• Test Coverage: Manual validation completed
• Security Review: ✅ Passed (MEDIUM risk accepted)
• Performance: ✅ Meets requirements (<1s response)

Monitoring Plan

• Daily: Usage statistics and error logs
• Weekly: Performance metrics and database size
• Monthly: Security audit and backup verification
• Quarterly: Feature review and optimization assessment

Deprecation Policy

• Notice Period: 3 months for major changes
• Migration Support: Data export tools provided
• Backward Compatibility: Maintained for minor versions

📞 Support & Contact

Technical Support

• Owner: 研发部
• Escalation: Contact skill repository maintainers
• Documentation: This file + inline code comments

Issue Reporting

• Bug Reports: Include error messages and reproduction steps
• Feature Requests: Provide use case and requirements
• Security Issues: Report immediately to security team

📦 Dependencies & Prerequisites

Runtime Requirements

• Python: 3.8+ (standard library only)
• No third-party dependencies: Reduces supply chain risk

File Structure

freezer-sample-locator/
├── SKILL.md                 # This file
├── scripts/
│   └── main.py             # Core implementation
└── data/
    └── samples.json        # Sample database (auto-created)

Installation & Setup

# No additional installation required - uses Python standard library
# Data directory created automatically on first run

---

Skill Classification: Tool/Script型 (MEDIUM Risk)
Compliance Status: ✅ Approved for production use
Next Review: 2026-05-06

Risk Assessment

| Risk Indicator | Assessment | Level | |----------------|------------|-------| | Code Execution | Python/R scripts executed locally | Medium | | Network Access | No external API calls | Low | | File System Access | Read input files, write output files | Medium | | Instruction Tampering | Standard prompt guidelines | Low | | Data Exposure | Output files saved to workspace | Low |

Security Checklist

• [ ] No hardcoded credentials or API keys
• [ ] No unauthorized file system access (../)
• [ ] Output does not expose sensitive information
• [ ] Prompt injection protections in place
• [ ] Input file paths validated (no ../ traversal)
• [ ] Output directory restricted to workspace
• [ ] Script execution in sandboxed environment
• [ ] Error messages sanitized (no stack traces exposed)
• [ ] Dependencies audited

Prerequisites

No additional Python packages required.

Evaluation Criteria

Success Metrics

• [ ] Successfully executes main functionality
• [ ] Output meets quality standards
• [ ] Handles edge cases gracefully
• [ ] Performance is acceptable

Test Cases

1. Basic Functionality: Standard input → Expected output
2. Edge Case: Invalid input → Graceful error handling
3. Performance: Large dataset → Acceptable processing time

Lifecycle Status

• Current Stage: Draft
• Next Review Date: 2026-03-06
• Known Issues: None
• Planned Improvements:
  • Performance optimization
  • Additional feature support