aicodesign

Provenance and review tracking for AI-generated code.

In fast-moving environments, using LLMs to generate code accelerates development, but it introduces varying levels of risk. aicodesign provides lightweight decorators/annotations to explicitly mark the review status and trust boundaries of AI-generated code running in production.

This is a polyglot monorepo containing implementations for multiple languages:

Implementations

• Python (3.10+): Decorators to tag functions and classes. Supports runtime execution warnings for unreviewed draft code.
• Java (25+): Annotations to tag classes, methods, and constructors with runtime retention for easy introspection.

The Three Tiers of Trust

This library standardizes AI code into three distinct categories based on human verification:

1. Draft (High Risk)

• Code Reviews: 0
• Test Reviews: 0
• Concept: The code and its tests were generated by an LLM and pushed without thorough human review. It is a raw draft. Fully covered (100% branch coverage) by unit-tests. Emits a runtime logger warning when executed (Python).

2. Blackbox (Medium Risk)

• Code Reviews: 0
• Test Reviews: 1+ (Human Verified)
• Concept: The internal logic is unreviewed (a black box), but the code is bounded by strict, human-reviewed unit tests. Fully covered (100% branch coverage) by unit-tests. We know what it does, even if we haven't audited how it does it.

3. Co-Signed (Lower Risk)

• Code Reviews: 1 (Human Verified)
• Test Reviews: 1+ (Human Verified)
• Concept: A human developer has reviewed the AI's logic and tests, officially putting their name on the line alongside the LLM. Fully covered (100% branch coverage) by unit-tests. Requires a mandatory reviewer argument.

Installation

Python (PyPI)

You can install the Python library directly from PyPI using your favorite package manager:

# Using pip
pip install aicodesign

# Using uv
uv add aicodesign

Java (Maven Central)

The Java library is published to Maven Central — no extra repository or authentication required.

1. Maven (pom.xml):

<dependency>
    <groupId>com.esamtrade</groupId>
    <artifactId>aicodesign</artifactId>
    <version>0.1.0</version>
</dependency>

2. Gradle (build.gradle.kts):

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.esamtrade:aicodesign:0.1.0")
}

Usage Examples

Python

from aicodesign import ai_draft, ai_blackbox, ai_co_signed

@ai_draft(ticket="HFT-101")
def calculate_momentum_alpha(prices):
    # Unreviewed logic and tests
    pass

@ai_blackbox(ticket="HFT-102", notes="Tests verify strict output boundaries")
def parse_exchange_feed(payload):
    # Logic is unreviewed, but a human vetted the test harness
    pass

@ai_co_signed(reviewer="alice.dev", ticket="HFT-103")
def update_order_book(book, new_orders):
    # A human has audited the logic and tests
    pass

Java

import dev.aicodesign.AiDraft;
import dev.aicodesign.AiBlackbox;
import dev.aicodesign.AiCoSigned;

public class OrderService {

    @AiDraft(ticket="HFT-101")
    public void calculateMomentumAlpha(Object prices) {
        // Unreviewed logic and tests
    }

    @AiBlackbox(ticket="HFT-102", notes="Tests verify strict output boundaries")
    public void parseExchangeFeed(Object payload) {
        // Logic is unreviewed, but a human vetted the test harness
    }

    @AiCoSigned(reviewer="alice.dev", ticket="HFT-103")
    public void updateOrderBook(Object book, Object newOrders) {
        // A human has audited the logic and tests
    }
}

License

MIT