Contributing

Project Structure

icrl

pyproject.toml

uv.lock

README.md

docs

api-reference

core-concepts

examples

guides

src

icrl

cli

providers

harbor

validators

examples

codebase_patterns_demo

exception_handling_demo

it_support_demo

preference_learning_demo

tests

icrl-ts

src

providers

adapters

examples

tests

web-example

convex

src

web-landing

src

Key Directories

Path	Purpose
`src/icrl/`	Python package: Agent, database, loop, retriever, curation
`src/icrl/cli/`	CLI entrypoints, TUI, tools, providers
`examples/`	Python demos (file system, Harbor, domain demos)
`tests/`	Python tests and walkthroughs
`icrl-ts/`	TypeScript package and web apps
`icrl-ts/src/`	TS library: Agent, database, loop, providers
`icrl-ts/web-example/`	Next.js + Convex demo app
`icrl-ts/web-landing/`	Marketing/landing site
`docs/`	Mintlify documentation

Development Setup

Prerequisites

Python 3.12+
uv for Python
Node 18+ and bun for TypeScript
API keys for demos: OPENAI_API_KEY and/or ANTHROPIC_API_KEY

Python (from repo root)

git clone https://github.com/SuperAce100/icrl.git
cd icrl

uv sync

Editable install is default with uv sync when developing from source.

TypeScript

cd icrl-ts
bun install
bun run build

Environment Variables

Create a .env file in the repo root (or in icrl-ts/ for TS demos):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

For Vertex AI usage: GOOGLE_APPLICATION_CREDENTIALS, VERTEXAI_PROJECT, VERTEXAI_LOCATION.

Running Tests

Python

# Mock LLM integration (no API keys)
uv run python tests/test_with_mock.py

# Agent API walkthrough
uv run python tests/agent_api_walkthrough.py

# Database API walkthrough
uv run python tests/database_api_walkthrough.py

# Harbor coding tests
uv run --with pytest python -m pytest tests/test_harbor_coding.py -v

TypeScript

cd icrl-ts
bun run tests:run

Linting and Formatting

Python

Uses ruff for linting and formatting:

uv run ruff check src tests examples
uv run ruff format src tests examples

TypeScript

cd icrl-ts
bun run lint
bun run typecheck

Submitting Changes

Fork the repository and create a branch from main.
Make changes with clear commits. Follow existing style (ruff for Python, project conventions for TS).
Run tests before submitting. Ensure uv run python tests/test_with_mock.py and uv run --with pytest python -m pytest tests/ pass for Python changes.
Open a pull request against main. Describe the change and link any related issues.

Documentation

Docs live in docs/ and use Mintlify. To preview locally:

bunx mint dev

Getting Started

Core Concepts

Guides

Examples

Contributing

Project Structure

Key Directories

Development Setup

Prerequisites

Python (from repo root)

TypeScript

Environment Variables

Running Tests

Python

TypeScript

Linting and Formatting

Python

TypeScript

Submitting Changes

Documentation

​Project Structure

​Key Directories

​Development Setup

​Prerequisites

​Python (from repo root)

​TypeScript

​Environment Variables

​Running Tests

​Python

​TypeScript

​Linting and Formatting

​Python

​TypeScript

​Submitting Changes

​Documentation

Project Structure

Key Directories

Development Setup

Prerequisites

Python (from repo root)

TypeScript

Environment Variables

Running Tests

Python

TypeScript

Linting and Formatting

Python

TypeScript

Submitting Changes

Documentation