Skip to content

Commit 6bd3616

Browse files
author
khayon
committed
Merge remote-tracking branch 'origin/main' into release/dev-to-main-20261115b
2 parents 26344aa + 2b0d127 commit 6bd3616

22 files changed

Lines changed: 481 additions & 50 deletions

File tree

‎packages/core/src/env-validation.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@ export function validateTrainingEnv(env: unknown): asserts env is TrainingEnv {
1616
assertFn(e, 'observe', 'TrainingEnv');
1717
assertFn(e, 'step', 'TrainingEnv');
1818
assertFn(e, 'reward', 'TrainingEnv');
19-
assertFn(e, 'done', 'TrainingEnv');
2019
assertFn(e, 'reset', 'TrainingEnv');
21-
for (const name of ['terminated', 'truncated']) {
20+
if (e.done === undefined && e.isDone === undefined) {
21+
assertFn(e, 'done', 'TrainingEnv');
22+
}
23+
for (const name of ['done', 'isDone', 'terminated', 'isTerminated', 'truncated', 'isTruncated']) {
2224
if (e[name] !== undefined) assertFn(e, name, 'TrainingEnv');
2325
}
2426

‎packages/core/src/ignition-env.ts‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,20 @@
1-
import { AgentInterface, AgentFactory, AlgorithmType, StepResult, TrainingEnv } from './types';
1+
import { AgentInterface, AgentFactory, AlgorithmType, EPISODE_FLAG_NAMES, StepResult, TrainingEnv } from './types';
22
import { validateTrainingEnv } from './env-validation';
33
import { mergeDefaults } from './defaults';
44

5+
function readFlag(env: TrainingEnv, names: readonly string[]): boolean | undefined {
6+
const record = env as TrainingEnv & Record<string, unknown>;
7+
for (const name of names) {
8+
const value = record[name];
9+
if (value === undefined) continue;
10+
if (typeof value !== 'function') {
11+
throw new TypeError(`${name} is not a function`);
12+
}
13+
return Boolean((value as () => unknown).call(env));
14+
}
15+
return undefined;
16+
}
17+
518
export class IgnitionEnv {
619
private env: TrainingEnv;
720
private _agent: AgentInterface | null = null;
@@ -93,8 +106,10 @@ export class IgnitionEnv {
93106
this.env.step(action);
94107
const observation = this.env.observe();
95108
const reward = this.env.reward();
96-
const truncated = this.env.truncated?.() ?? false;
97-
const terminated = this.env.terminated?.() ?? (this.env.done() && !truncated);
109+
// EPISODE_FLAG_NAMES: canonical method first, then is* alias; first defined function wins.
110+
const truncated = readFlag(this.env, EPISODE_FLAG_NAMES.truncated) ?? false;
111+
const terminated = readFlag(this.env, EPISODE_FLAG_NAMES.terminated)
112+
?? ((readFlag(this.env, EPISODE_FLAG_NAMES.done) ?? false) && !truncated);
98113
if (!greedy) {
99114
agent.remember({ state: this.currentState, action, reward, nextState: observation, terminated, truncated });
100115
if (agent.shouldTrain?.() ?? true) await agent.train();

‎packages/core/src/index.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ export type {
1818
BoxSpace,
1919
MultiDiscreteSpace,
2020
} from './types';
21+
export { EPISODE_FLAG_NAMES } from './types';
2122

2223
export { mergeDefaults } from './defaults';
2324
export { validateTrainingEnv, validateInferenceEnv } from './env-validation';
24-
export { ExperienceSchema } from './schemas';
25+
export { ExperienceSchema, TrainingEnvSchema } from './schemas';

‎packages/core/src/schemas.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
import { z } from 'zod';
22

3+
function functionField(label: string) {
4+
return z.custom<(...args: never[]) => unknown>(
5+
(val: unknown) => typeof val === 'function',
6+
{ message: `${label} must be a function` },
7+
);
8+
}
9+
310
// ─── Experience ──────────────────────────────────────────────────────────────
411

512
export const ExperienceSchema = z.object({
@@ -11,3 +18,24 @@ export const ExperienceSchema = z.object({
1118
truncated: z.boolean({ message: 'truncated must be a boolean' }),
1219
info: z.record(z.unknown()).optional(),
1320
});
21+
22+
/** Same optional done/isDone pair as TrainingEnv; at least one function is required. */
23+
export const TrainingEnvSchema = z.object({
24+
actions: z.union([
25+
z.array(z.string()).min(1, { message: 'TrainingEnv.actions must have at least one action' }),
26+
z.number().positive({ message: 'TrainingEnv.actions must have at least one action' }),
27+
], { message: 'TrainingEnv.actions must be a string[] or a positive number' }),
28+
observe: functionField('observe'),
29+
step: functionField('step'),
30+
reward: functionField('reward'),
31+
reset: functionField('reset'),
32+
done: functionField('done').optional(),
33+
isDone: functionField('isDone').optional(),
34+
terminated: functionField('terminated').optional(),
35+
isTerminated: functionField('isTerminated').optional(),
36+
truncated: functionField('truncated').optional(),
37+
isTruncated: functionField('isTruncated').optional(),
38+
}).refine(
39+
(env) => typeof env.done === 'function' || typeof env.isDone === 'function',
40+
{ message: 'TrainingEnv must implement done() or isDone() as a function' },
41+
);

‎packages/core/src/types.ts‎

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,16 @@ export interface CheckpointableAgent extends AgentInterface {
8888

8989
// ─── Environment interfaces ─────────────────────────────────────────────────
9090

91+
/**
92+
* Lookup order for episode-end flags: canonical method first, then the `is*` alias.
93+
* The first defined function wins. Construction requires `done()` or `isDone()`.
94+
*/
95+
export const EPISODE_FLAG_NAMES = {
96+
truncated: ['truncated', 'isTruncated'],
97+
terminated: ['terminated', 'isTerminated'],
98+
done: ['done', 'isDone'],
99+
} as const;
100+
91101
/**
92102
* Contract for a training environment. The developer implements this
93103
* to describe their game/simulation for RL training.
@@ -101,12 +111,22 @@ export interface TrainingEnv {
101111
step(action: number | number[]): void;
102112
/** Return the reward for the current state */
103113
reward(): number;
104-
/** Return true if the episode is over */
105-
done(): boolean;
114+
/**
115+
* Return true if the episode is over.
116+
* Required unless isDone() is provided. Construction (type, Zod, validateTrainingEnv)
117+
* accepts done() alone, isDone() alone, or both.
118+
*/
119+
done?(): boolean;
120+
/** Retrocompatible alias of done(). Accepted alone when done() is omitted. */
121+
isDone?(): boolean;
106122
/** Optional explicit terminal condition; overrides legacy done(). */
107123
terminated?(): boolean;
124+
/** Retrocompatible alias of terminated(). */
125+
isTerminated?(): boolean;
108126
/** Optional external episode limit (default: false). */
109127
truncated?(): boolean;
128+
/** Retrocompatible alias of truncated(). */
129+
isTruncated?(): boolean;
110130
/** Reset the environment for a new episode */
111131
reset(): void;
112132
}
@@ -130,3 +150,21 @@ export type AlgorithmType = 'dqn' | 'double-dqn' | 'ppo' | 'qtable';
130150
* Used by IgnitionEnv.train() to auto-create agents.
131151
*/
132152
export type AgentFactory = (config: Record<string, unknown>) => AgentInterface;
153+
154+
type TrainingEnvCore = {
155+
actions: string[] | number;
156+
observe(): number[];
157+
step(action: number | number[]): void;
158+
reward(): number;
159+
reset(): void;
160+
};
161+
162+
type ExtendsTrainingEnv<T> = T extends TrainingEnv ? true : false;
163+
164+
/** Compile-time check: canonical only, alias only, and both must satisfy TrainingEnv. */
165+
const trainingEnvDoneCombinations: {
166+
canonical: ExtendsTrainingEnv<TrainingEnvCore & { done(): boolean }>;
167+
alias: ExtendsTrainingEnv<TrainingEnvCore & { isDone(): boolean }>;
168+
both: ExtendsTrainingEnv<TrainingEnvCore & { done(): boolean; isDone(): boolean }>;
169+
} = { canonical: true, alias: true, both: true };
170+
void trainingEnvDoneCombinations;

‎packages/core/test/env-validation.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,23 @@ describe('validateTrainingEnv', () => {
6666
expect(() => validateTrainingEnv({ ...validTrainingEnv, observe: 'nope' })).toThrow(/observe.*function/);
6767
});
6868

69+
it('accepts canonical done() alone', () => {
70+
expect(() => validateTrainingEnv(validTrainingEnv)).not.toThrow();
71+
});
72+
73+
it('accepts alias isDone() alone', () => {
74+
const { done, ...rest } = validTrainingEnv;
75+
expect(() => validateTrainingEnv({ ...rest, isDone: () => false })).not.toThrow();
76+
});
77+
78+
it('accepts both done() and isDone()', () => {
79+
expect(() => validateTrainingEnv({ ...validTrainingEnv, isDone: () => false })).not.toThrow();
80+
});
81+
82+
it('throws if isTerminated is not a function', () => {
83+
expect(() => validateTrainingEnv({ ...validTrainingEnv, isTerminated: true })).toThrow(/isTerminated/);
84+
});
85+
6986
it('accepts a class instance (duck typing)', () => {
7087
class MyEnv {
7188
actions = ['a', 'b'];

‎packages/core/test/episode-end.test.ts‎

Lines changed: 81 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,22 @@
11
import { expect, it, vi } from 'vitest';
22
import { IgnitionEnv } from '../src/ignition-env';
3+
import type { TrainingEnv } from '../src/types';
4+
5+
function baseWorld() {
6+
return {
7+
actions: 2,
8+
observe: () => [0],
9+
step: () => {},
10+
reward: () => 0,
11+
reset: () => {},
12+
};
13+
}
14+
15+
async function stepWith(world: object) {
16+
const loop = new IgnitionEnv({ ...baseWorld(), ...world } as TrainingEnv);
17+
loop.agent = { getAction: async () => 0, remember: () => {}, train: async () => {} };
18+
return loop.step();
19+
}
320

421
it.each(['step', 'inferStep'] as const)('%s reports truncation and resets without losing the last observation', async (method) => {
522
let position = 0;
@@ -16,6 +33,62 @@ it.each(['step', 'inferStep'] as const)('%s reports truncation and resets withou
1633
if (method === 'step') expect(remember).toHaveBeenCalledWith(expect.objectContaining({ nextState: [5], terminated: false, truncated: true }));
1734
});
1835

36+
it('canonical terminated() alone sets terminated', async () => {
37+
expect(await stepWith({ done: () => false, terminated: () => true })).toMatchObject({ terminated: true, truncated: false });
38+
});
39+
40+
it('alias isTerminated() alone sets terminated', async () => {
41+
expect(await stepWith({ done: () => false, isTerminated: () => true })).toMatchObject({ terminated: true, truncated: false });
42+
});
43+
44+
it('prefers canonical terminated() over isTerminated() when both are defined', async () => {
45+
const terminated = vi.fn(() => false);
46+
const isTerminated = vi.fn(() => true);
47+
expect(await stepWith({ done: () => true, terminated, isTerminated })).toMatchObject({ terminated: false, truncated: false });
48+
expect(terminated).toHaveBeenCalledTimes(1);
49+
expect(isTerminated).not.toHaveBeenCalled();
50+
});
51+
52+
it('canonical truncated() alone sets truncated', async () => {
53+
expect(await stepWith({ done: () => false, truncated: () => true })).toMatchObject({ terminated: false, truncated: true });
54+
});
55+
56+
it('alias isTruncated() alone sets truncated', async () => {
57+
expect(await stepWith({ done: () => false, isTruncated: () => true })).toMatchObject({ terminated: false, truncated: true });
58+
});
59+
60+
it('prefers canonical truncated() over isTruncated() when both are defined', async () => {
61+
const truncated = vi.fn(() => false);
62+
const isTruncated = vi.fn(() => true);
63+
expect(await stepWith({ done: () => false, truncated, isTruncated })).toMatchObject({ terminated: false, truncated: false });
64+
expect(truncated).toHaveBeenCalledTimes(1);
65+
expect(isTruncated).not.toHaveBeenCalled();
66+
});
67+
68+
it('canonical done() alone sets terminated', async () => {
69+
expect(await stepWith({ done: () => true })).toMatchObject({ terminated: true, truncated: false });
70+
});
71+
72+
it('alias isDone() alone sets terminated', async () => {
73+
expect(await stepWith({ isDone: () => true })).toMatchObject({ terminated: true, truncated: false });
74+
});
75+
76+
it('prefers canonical done() over isDone() when both are defined', async () => {
77+
const done = vi.fn(() => false);
78+
const isDone = vi.fn(() => true);
79+
expect(await stepWith({ done, isDone })).toMatchObject({ terminated: false, truncated: false });
80+
expect(done).toHaveBeenCalledTimes(1);
81+
expect(isDone).not.toHaveBeenCalled();
82+
});
83+
84+
it('honors isTerminated/isTruncated aliases over done()', async () => {
85+
const reset = vi.fn();
86+
expect(await stepWith({
87+
done: () => true, reset, isTerminated: () => false, isTruncated: () => true,
88+
})).toMatchObject({ terminated: false, truncated: true });
89+
expect(reset).toHaveBeenCalledTimes(1);
90+
});
91+
1992
it.each([
2093
{ explicit: undefined, truncated: undefined, terminal: true, cut: false },
2194
{ explicit: true, truncated: true, terminal: true, cut: true },
@@ -32,8 +105,11 @@ it.each([
32105
expect(reset).toHaveBeenCalledTimes(terminal || cut ? 1 : 0);
33106
});
34107

35-
it.each(['terminated', 'truncated'])('rejects a non-function %s callback at construction', (name) => {
36-
expect(() => new IgnitionEnv({ actions: 2, observe: () => [0], step: () => {},
37-
reward: () => 0, done: () => false, reset: () => {}, [name]: true,
38-
})).toThrow(new RegExp(name));
39-
});
108+
it.each(['terminated', 'truncated', 'isTerminated', 'isTruncated', 'isDone'])(
109+
'rejects a non-function %s callback at construction',
110+
(name) => {
111+
expect(() => new IgnitionEnv({ actions: 2, observe: () => [0], step: () => {},
112+
reward: () => 0, done: () => false, reset: () => {}, [name]: true,
113+
})).toThrow(new RegExp(name));
114+
},
115+
);

‎packages/core/test/ignition-env.test.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { describe, it, expect } from 'vitest';
1+
import { describe, it, expect, vi } from 'vitest';
22
import { IgnitionEnv } from '../src/ignition-env';
33
import type { TrainingEnv } from '../src/types';
44

@@ -67,4 +67,25 @@ describe('IgnitionEnv with TrainingEnv interface', () => {
6767
const obj = { actions: ['a', 'b'], observe: () => [1], step: () => {}, reward: () => 0, done: () => false, reset: () => {} };
6868
expect(() => new IgnitionEnv(obj)).not.toThrow();
6969
});
70+
71+
it('runs 10 steps on a valid config and calls isTerminated and isTruncated', async () => {
72+
const isTerminated = vi.fn(() => false);
73+
const isTruncated = vi.fn(() => false);
74+
const env = new IgnitionEnv({
75+
actions: 2,
76+
observe: () => [0],
77+
step() {},
78+
reward: () => 0,
79+
done: () => false,
80+
reset() {},
81+
isTerminated,
82+
isTruncated,
83+
});
84+
env.agent = { getAction: async () => 0, remember() {}, train: async () => {} };
85+
for (let i = 0; i < 10; i++) {
86+
await expect(env.step()).resolves.toMatchObject({ terminated: false, truncated: false });
87+
}
88+
expect(isTerminated).toHaveBeenCalledTimes(10);
89+
expect(isTruncated).toHaveBeenCalledTimes(10);
90+
});
7091
});

‎packages/core/test/schemas.test.ts‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { describe, it, expect } from 'vitest';
2-
import { ExperienceSchema } from '../src/schemas';
2+
import { ExperienceSchema, TrainingEnvSchema } from '../src/schemas';
3+
import { EPISODE_FLAG_NAMES } from '../src/types';
34
import type { Experience } from '../src/types';
45

56
describe('ExperienceSchema', () => {
@@ -33,3 +34,53 @@ describe('ExperienceSchema', () => {
3334
).toThrow();
3435
});
3536
});
37+
38+
describe('TrainingEnvSchema', () => {
39+
const valid = {
40+
actions: 2,
41+
observe: () => [0],
42+
step: () => {},
43+
reward: () => 0,
44+
reset: () => {},
45+
done: () => false,
46+
};
47+
48+
it('accepts isTerminated, isTruncated and isDone aliases', () => {
49+
expect(() => TrainingEnvSchema.parse({
50+
...valid,
51+
isTerminated: () => false,
52+
isTruncated: () => false,
53+
isDone: () => false,
54+
})).not.toThrow();
55+
});
56+
57+
it('accepts canonical done() alone', () => {
58+
expect(() => TrainingEnvSchema.parse(valid)).not.toThrow();
59+
});
60+
61+
it('accepts alias isDone() alone', () => {
62+
const { done: _done, ...rest } = valid;
63+
expect(() => TrainingEnvSchema.parse({ ...rest, isDone: () => false })).not.toThrow();
64+
});
65+
66+
it('accepts both done() and isDone()', () => {
67+
expect(() => TrainingEnvSchema.parse({ ...valid, isDone: () => false })).not.toThrow();
68+
});
69+
70+
it('rejects an env with neither done nor isDone', () => {
71+
const { done: _done, ...rest } = valid;
72+
expect(() => TrainingEnvSchema.parse(rest)).toThrow(/done\(\) or isDone\(\)/);
73+
});
74+
75+
it('rejects a non-function isTerminated', () => {
76+
expect(() => TrainingEnvSchema.parse({ ...valid, isTerminated: true })).toThrow(/isTerminated/);
77+
});
78+
});
79+
80+
describe('EPISODE_FLAG_NAMES', () => {
81+
it('lists the canonical method before the is* alias for every flag', () => {
82+
expect(EPISODE_FLAG_NAMES.terminated).toEqual(['terminated', 'isTerminated']);
83+
expect(EPISODE_FLAG_NAMES.truncated).toEqual(['truncated', 'isTruncated']);
84+
expect(EPISODE_FLAG_NAMES.done).toEqual(['done', 'isDone']);
85+
});
86+
});

‎packages/web/app/[locale]/(default)/blog/[slug]/page.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ export default async function EnvironmentArticlePage({ params }: ArticleParams)
4141
<h1 className="h1 mb-6">{article.title}</h1>
4242
<p className="text-xl text-slate-300">{article.description}</p>
4343
</header>
44-
<div className="prose prose-invert prose-lg max-w-none prose-headings:text-slate-100 prose-a:text-indigo-300 prose-pre:overflow-x-auto prose-pre:bg-slate-950 prose-img:rounded-xl prose-img:border prose-img:border-slate-700">
44+
<div className="prose prose-invert prose-lg max-w-none prose-headings:font-semibold prose-headings:text-slate-100 prose-a:text-indigo-300 prose-pre:overflow-x-auto prose-pre:bg-slate-950 prose-img:rounded-xl prose-img:border prose-img:border-slate-700">
4545
<BlogContent source={readBlogArticle(article, locale)} />
4646
</div>
4747
</article>

0 commit comments

Comments
 (0)