ai-microcore: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, etc.) when working with code in this repository.

Overview

AI MicroCore (ai-microcore, importable as microcore) is a thin adapter layer over LLM providers and vector/semantic-search databases. The whole point is provider-agnosticism: application code calls llm(...), tpl(...), texts.search(...) and the concrete backend (OpenAI, Anthropic, Google, a CLI tool, a local Transformers model, an arbitrary Python function, ChromaDB, Qdrant, ...) is selected purely by configuration. When changing behavior, preserve this property — adding a parameter or branch that forces application code to know which backend is active works against the core design.

Commands

Tests run locally with pytest (no Docker required); the Makefile targets wrap the same commands in a Docker container (make test, make cs, make black) and are mainly for the maintainer's workflow.

pip install -r requirements/dev.txt   # test + lint + build tooling

pytest                                 # runs tests/basic (the default testpath, no network)
pytest tests/basic/test_llm.py         # single file
pytest tests/basic/test_llm.py::test_name   # single test
pytest tests/apis                      # hits REAL API services; needs .env.test.* + keys

flake8 microcore tests examples        # max-line-length=100 (.flake8)
pylint microcore                       # config in .pylintrc
black microcore tests examples         # formatter; commits are expected to be black-clean

python -m microcore test-llm <.env-file> [<prompt>]   # smoke-test a provider config live

Note pyproject.toml sets testpaths = ["tests/basic"] and asyncio_mode = "auto", so a bare pytest only runs the basic suite. Other suites: tests/extended, tests/cache, tests/local (Transformers), tests/apis (live). CI (.github/workflows/tests.yml) runs the basic suite on Python 3.10–3.14 and pylint separately.

Architecture