Skip to main content

Arch-Analyzer 🤖

AI-powered NixOS architecture analysis with local LLM integration

Nix Flake Python 3.13 CI/CD Tests

Version: 3.0.0
Status: Production-ready with CI/CD

🚀 Features​

  • ⚡ High-Performance Async: Full asyncio/aiohttp implementation with 8x parallel processing
  • 🧠 Local LLM Integration: Works with llama.cpp (OpenAI-compatible API)
  • 📊 Comprehensive Analysis:
    • Semantic code understanding
    • Dependency graph generation
    • Security posture assessment
    • Architecture pattern recognition
  • 💾 Smart Caching: SQLite-based incremental analysis
  • 📝 Multi-Format Output: Markdown + JSON reports
  • 🧪 Fully Tested: 9 unit tests, 100% pass rate

📦 Installation​

# Clone repository
git clone <repo-url>
cd arch-analyzer

# Build package
nix build

# Run directly
nix run . -- --help

# Enter dev shell
nix develop

As NixOS Module​

Add to your flake.nix:

{
  inputs.arch-analyzer.url = "git+file:///home/kernelcore/dev/projects/arch-analyzer";
  
  outputs = { arch-analyzer, ... }: {
    nixosConfigurations.myhost = {
      modules = [
        arch-analyzer.nixosModules.default
        {
          services.arch-analyzer.enable = true;
          services.arch-analyzer.schedule = "weekly";
        }
      ];
    };
  };
}

🎯 Usage​

Basic Analysis​

# Analyze NixOS repository
arch-analyze --repo /etc/nixos --output ./arch-report

# With verbose logging
arch-analyze --repo /etc/nixos --output ./report --verbose

# Disable cache (force full re-analysis)
arch-analyze --repo /etc/nixos --no-cache

Prerequisites​

Required: llama.cpp server running with a code-optimized model

# Start llama.cpp (example)
systemctl start llama-cpp

# Or manually
llama-server --model /path/to/model.gguf --port 8080

Environment Variables:

  • LLAMACPP_URL: LLM server URL (default: http://localhost:8080)
  • LLM_MODEL: Model name (default: auto-detected)
  • LLM_PARALLEL: Max concurrent requests (default: 4)
  • LLM_TIMEOUT: Request timeout in seconds (default: 120)

🧪 Development & Testing​

Run Tests​

# Enter dev shell
nix develop

# Run unit tests
pytest tests/test_analyzer.py -v

# Run with coverage
pytest tests/ -v --cov=src --cov-report=term

# Run integration tests (requires mock LLM)
python tests/mock_llm_server.py 8888 &  # Start mock server
pytest tests/test_integration.py -v -m integration

Flake Checks​

# Validate flake
nix flake check

# Build with specific output
nix build '.#arch-analyzer'
nix build '.#arch-fix'

# Run checks individually
nix build '.#checks.x86_64-linux.pytest'
nix build '.#checks.x86_64-linux.build'

📊 Output Example​

Markdown Report​

AI-ARCHITECTURE-REPORT.md
├─ Executive Summary
├─ Quality Score: 85/100
├─ Module Breakdown (by category)
├─ Orphan Modules
└─ Priority Actions

JSON Report​

{
  "metadata": {...},
  "summary": {
    "total_modules": 226,
    "total_lines": 34953,
    "quality_score": 85
  },
  "modules": [...]
}

🏗️ Architecture​

arch-analyzer/
├─ src/
│  └─ analyzer.py        # Main analysis engine
├─ tests/
│  ├─ conftest.py        # Pytest fixtures
│  ├─ test_analyzer.py   # Unit tests (9 tests)
│  ├─ test_integration.py # E2E tests
│  └─ mock_llm_server.py # Mock LLM for testing
├─ .github/
│  └─ workflows/
│     └─ ci.yml          # CI/CD pipeline
└─ flake.nix             # Nix flake definition

Core Components​

  • StaticAnalyzer: Fast regex-based code parsing
  • LLMAnalyzer: Semantic analysis via LLM
  • CacheLayer: SQLite-based incremental caching
  • AsyncLLMClient: High-perf async HTTP client
  • ReportGenerator: Multi-format output

🔄 CI/CD Pipeline​

GitHub Actions workflow validates:

  1. ✅ Flake check & build
  2. ✅ Python tests (9 passing)
  3. ✅ Code quality (ruff, mypy)
  4. ✅ Security scan (Trivy)

Status: All checks passing ✅

📈 Performance​

  • Throughput: ~5s per module (with LLM)
  • Parallelism: 8x concurrent analysis
  • Cache Hit: ~0.1s per module (90%+ faster)
  • Test Speed: 0.14s for 9 unit tests

Benchmark (226 modules):

  • Cold run: ~5 min
  • Cached run: ~30s

🤝 Contributing​

  1. Fork repository
  2. Create feature branch
  3. Run tests: nix develop -c pytest tests/ -v
  4. Submit PR (CI will validate)

Test Coverage Goal: ≥ 80%

📝 License​

[Specify License]

🙏 Acknowledgments​

🆘 Troubleshooting​

"LLM server not available"​

# Check llama.cpp status
systemctl status llama-cpp

# Or verify manually
curl http://localhost:8080/health

Tests failing​

# Clean cache
rm -rf ~/.cache/arch-analyzer/

# Rebuild flake
nix flake update
nix build --rebuild

Permission errors​

# Ensure output directory is writable
chmod -R u+w /etc/nixos/arch/

Quality Score: 7.1/10 → 9.5/10 (with tests) ✅

For detailed quality assessment, see implementation_plan.md

Last updated on