Skip to main content

​
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

PathPurpose
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

  1. Fork the repository and create a branch from main.
  2. Make changes with clear commits. Follow existing style (ruff for Python, project conventions for TS).
  3. 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.
  4. 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