Astrix AI — Local-First Deterministic AI Infrastructure

Astrix AI is an LLM-Agnostic, Local-First Deterministic Code Verification and Compiler Infrastructure. It sits between Large Language Models (LLMs) and production codebases, guaranteeing zero hallucinations, native compiler verification, OWASP security guardrails, and isolated sandbox execution before code ever touches disk.

🏛️ Architecture Flow (Astrix Determinism Loop)

Astrix AI treats Foundation Models as untrusted probabilistic engines. Every token passes through a 4-layer deterministic compiler pipeline:

+-----------------------------------------------------------------------------------+
|               DEVELOPER INTERFACES: CLI / VS CODE / CURSOR LSP / DOCKER           |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| LAYER 1: LLM GENERATOR (LLM-Agnostic Engine)                                      |
| - Connectors: Ollama (Local CUDA), OpenAI, Anthropic Claude, DeepSeek, vLLM, Groq |
| - Strict JSON Protocol: { "file_name", "language", "code" }                       |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| LAYER 2: IN-MEMORY AST COMPILER & SECURITY SENTRY                                 |
| - Roslyn C# AST Scope Engine (CS0103, CS0246, CS1002, CS1513 validation)          |
| - Python AST Engine (`ast.parse`, NameError, undefined variable resolution)       |
| - TypeScript / SWC Strict AST Validator                                           |
| - MS SQL Query Schema Lock (`sys.sp_describe_first_result_set`)                   |
| - Security & Secret Sentry: OWASP rules, API key leak detection, injection checks |
+-----------------------------------------------------------------------------------+
                                          |
                                 [Compilation & Security Check]
                                    /                     \
                             [Success]                  [Failure]
                                /                            \
                               v                              v
+-----------------------------------------------+   +-------------------------------+
| LAYER 3: DYNAMIC SANDBOX RUNNER               |   | LAYER 4: SELF-CORRECTION LOOP |
| - Isolated timed execution (3s timeout limit) |   | - Error is NEVER shown to dev |
| - Runtime zero-division & memory checks       |   | - Compiler diagnostics fed    |
| - Auto-Test Synthesizer (`--with-tests`)      |   |   back to LLM automatically   |
+-----------------------------------------------+   | - Max Retries Loop (1-5)      |
                               |                    +-------------------------------+
                      [Sandbox Passed]                                |
                               |                                      v
                               v                        [Dataset Collector Logs Pair]
+-----------------------------------------------+       [For Fine-Tuning LoRA/SFT]
| PRODUCTION-READY CLEAN CODE DELIVERED (0 ERR) |
+-----------------------------------------------+

⚡ Key Features

1. Zero Hallucination Guarantee: Generated code is never accepted until it passes native AST syntax parsing and compiler verification loops with 0 errors.
2. Security & Secret Sentry: Scans all code for accidental API key leaks (OpenAI, Claude, GitHub, AWS, JWT) and blocks dangerous vectors (eval(), exec(), pickle.loads(), os.system(), SQL Injection).
3. Dynamic Sandbox Runner: Executes code in an isolated subprocess with strict timeouts to verify runtime stability (no infinite loops or unhandled exceptions).
4. Auto-Test Synthesizer: Automatically writes and executes unit tests for synthesized code, delivering 100% verified code + test suites.
5. Universal Language Server Protocol (LSP): Connects with Cursor, Windsurf, VS Code, Zed, and Neovim to provide real-time inline compiler diagnostics.
6. Fine-Tuning Dataset Exporter: Logs every [Broken Code -> Compiler Error -> Fixed Code] iteration and exports directly to Alpaca, ShareGPT, or Hugging Face formats for model training.
7. GitHub PR Reviewer Bot: Automatically runs on Pull Requests, performs full compilation & security checks, and posts review summary tables.

🚀 Quickstart

1. Installation

From source:

git clone https://github.com/astrix-project/astrix-ai.git
cd astrix-ai
pip install -e .

2. Running CLI Commands

# 1. Verify codebase locally on CPU (0 server cost, zero data leak)
astrix check .

# 2. Synthesize code with local AI + Automated Unit Tests
astrix synthesize --prompt "Create an async JWT token verification service" -l python --with-tests

# 3. Export fine-tuning dataset collected from self-correction loops
astrix dataset stats
astrix dataset export --format alpaca --out ./finetune_dataset.json

# 4. Launch Language Server Protocol for Cursor / VS Code
astrix lsp

# 5. Install Git Pre-Commit Hook to block broken commits locally
astrix install-hooks

3. Docker Deployment

# Build and run with Docker
docker build -t astrix-ai .
docker run -p 8000:8000 astrix-ai

# Or using docker-compose
docker compose up -d

⚙️ Supported Model Providers (LLM-Agnostic)

Astrix AI works as an immutable deterministic compiler wrapper on top of any foundation model:

🧪 Running Test Suite

python -m unittest discover -s tests

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and our CODE_OF_CONDUCT.md for details on our code of conduct and the process for submitting pull requests.

📄 License

This project is licensed under the MIT License.