API Reference for evolution-svc

evolution_svc

Evolution service for adapter evaluation, evolution, promotion, and pruning.

Modules

dependencies

Dependency injection for FastAPI endpoints.

Functions
get_db 
get_db() -> Generator[Session, None, None]

Provide a database session for dependency injection.

Yields:

Type Description
Session

Database session that automatically commits or rolls back.
Source code in services/evolution-svc/src/evolution_svc/dependencies.py 
10
11
12
13
14
15
16
17
def get_db() -> Generator[Session, None, None]:
    """Provide a database session for dependency injection.

    Yields:
        Database session that automatically commits or rolls back.
    """
    with Session(engine) as session:
        yield session

main

FastAPI application for the evolution service.

Functions
lifespan async 
lifespan(app: FastAPI)

Manage the lifecycle of the FastAPI application.

Source code in services/evolution-svc/src/evolution_svc/main.py 
16
17
18
19
20
21
22
23
@asynccontextmanager
async def lifespan(app: FastAPI):
    """Manage the lifecycle of the FastAPI application."""
    logger.info("Starting up evolution service...")
    create_db_and_tables()
    logger.info("Database initialized successfully")
    yield
    logger.info("Shutdown complete")
health_check async 
health_check()

Liveness probe - is the service running?

Source code in services/evolution-svc/src/evolution_svc/main.py 
30
31
32
33
@app.get("/health")
async def health_check():
    """Liveness probe - is the service running?"""
    return {"status": "healthy", "service": "evolution-svc"}

models

SQLModel tables for evolution job tracking.

Classes
EvolutionJob

Bases: SQLModel

Persistent record of an evolution job.

routers

Router modules for evolution service endpoints.

Modules
evolution

Evolution router with stub 501 endpoints.

Classes Functions
evaluate_adapter async 
evaluate_adapter(
    request: EvaluationRequest,
) -> JSONResponse

Evaluate an adapter's performance.

Parameters:

Name Type Description Default
request EvaluationRequest

Evaluation parameters including adapter_id and task_type.

 required

Returns:

Type Description
JSONResponse

JSONResponse with evaluation metrics (pass_rate, fitness_score,
JSONResponse

generalization_delta).

Raises:

Type Description
HTTPException

501 while not yet implemented.
Example

body = {"adapter_id": "a-1", "task_type": "code-gen"} response = client.post("/evaluate", json=body) response.status_code 200 'fitness_score' in response.json() True

Source code in services/evolution-svc/src/evolution_svc/routers/evolution.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
@router.post("/evaluate")
async def evaluate_adapter(request: EvaluationRequest) -> JSONResponse:
    """Evaluate an adapter's performance.

    Args:
        request: Evaluation parameters including adapter_id and task_type.

    Returns:
        JSONResponse with evaluation metrics (pass_rate, fitness_score,
        generalization_delta).

    Raises:
        HTTPException: 501 while not yet implemented.

    Example:
        >>> body = {"adapter_id": "a-1", "task_type": "code-gen"}
        >>> response = client.post("/evaluate", json=body)
        >>> response.status_code
        200
        >>> 'fitness_score' in response.json()
        True
    """
    return JSONResponse(status_code=501, content={"detail": "Not Implemented"})
evolve_adapters async 
evolve_adapters(request: EvolveRequest) -> JSONResponse

Evolve adapters via crossover/mutation.

Parameters:

Name Type Description Default
request EvolveRequest

Evolution parameters including adapter_ids and task_type.

 required

Returns:

Type Description
JSONResponse

JSONResponse with evolved adapter information including new adapter_id
JSONResponse

and lineage details.

Raises:

Type Description
HTTPException

501 while not yet implemented.
Example

body = {"adapter_ids": ["a-1", "a-2"], "task_type": "gen"} response = client.post("/evolve", json=body) response.status_code 200 'adapter_id' in response.json() True

Source code in services/evolution-svc/src/evolution_svc/routers/evolution.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@router.post("/evolve")
async def evolve_adapters(request: EvolveRequest) -> JSONResponse:
    """Evolve adapters via crossover/mutation.

    Args:
        request: Evolution parameters including adapter_ids and task_type.

    Returns:
        JSONResponse with evolved adapter information including new adapter_id
        and lineage details.

    Raises:
        HTTPException: 501 while not yet implemented.

    Example:
        >>> body = {"adapter_ids": ["a-1", "a-2"], "task_type": "gen"}
        >>> response = client.post("/evolve", json=body)
        >>> response.status_code
        200
        >>> 'adapter_id' in response.json()
        True
    """
    return JSONResponse(status_code=501, content={"detail": "Not Implemented"})
promote_adapter async 
promote_adapter(request: PromoteRequest) -> JSONResponse

Promote an adapter to a higher tier.

Parameters:

Name Type Description Default
request PromoteRequest

Promotion parameters including adapter_id and target_level.

 required

Returns:

Type Description
JSONResponse

JSONResponse with promotion confirmation including adapter_id and
JSONResponse

new tier level.

Raises:

Type Description
HTTPException

501 while not yet implemented.
Example

body = {"adapter_id": "a-1", "target_level": "domain"} response = client.post("/promote", json=body) response.status_code 200 'adapter_id' in response.json() True

Source code in services/evolution-svc/src/evolution_svc/routers/evolution.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@router.post("/promote")
async def promote_adapter(request: PromoteRequest) -> JSONResponse:
    """Promote an adapter to a higher tier.

    Args:
        request: Promotion parameters including adapter_id and target_level.

    Returns:
        JSONResponse with promotion confirmation including adapter_id and
        new tier level.

    Raises:
        HTTPException: 501 while not yet implemented.

    Example:
        >>> body = {"adapter_id": "a-1", "target_level": "domain"}
        >>> response = client.post("/promote", json=body)
        >>> response.status_code
        200
        >>> 'adapter_id' in response.json()
        True
    """
    return JSONResponse(status_code=501, content={"detail": "Not Implemented"})
prune_adapter async 
prune_adapter(request: PruneRequest) -> JSONResponse

Prune an underperforming adapter.

Parameters:

Name Type Description Default
request PruneRequest

Pruning parameters including adapter_id to remove.

 required

Returns:

Type Description
JSONResponse

JSONResponse with pruning confirmation including adapter_id and
JSONResponse

pruned status.

Raises:

Type Description
HTTPException

501 while not yet implemented.
Example

response = client.post("/prune", json={"adapter_id": "a-1"}) response.status_code 200 'adapter_id' in response.json() True

Source code in services/evolution-svc/src/evolution_svc/routers/evolution.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
@router.post("/prune")
async def prune_adapter(request: PruneRequest) -> JSONResponse:
    """Prune an underperforming adapter.

    Args:
        request: Pruning parameters including adapter_id to remove.

    Returns:
        JSONResponse with pruning confirmation including adapter_id and
        pruned status.

    Raises:
        HTTPException: 501 while not yet implemented.

    Example:
        >>> response = client.post("/prune", json={"adapter_id": "a-1"})
        >>> response.status_code
        200
        >>> 'adapter_id' in response.json()
        True
    """
    return JSONResponse(status_code=501, content={"detail": "Not Implemented"})

schemas

Pydantic request/response schemas for evolution service.

Classes
EvaluationRequest

Bases: BaseModel

Request to evaluate an adapter's performance.

EvaluationResponse

Bases: BaseModel

Response containing adapter evaluation metrics.

EvolveRequest

Bases: BaseModel

Request to evolve adapters via crossover/mutation.

PromoteRequest

Bases: BaseModel

Request to promote an adapter to a higher tier.

PruneRequest

Bases: BaseModel

Request to prune an underperforming adapter.

storage

Database storage configuration for evolution service.

Functions
create_db_and_tables 
create_db_and_tables() -> None

Create all database tables.

Source code in services/evolution-svc/src/evolution_svc/storage.py 
 9
10
11
def create_db_and_tables() -> None:
    """Create all database tables."""
    SQLModel.metadata.create_all(engine)