Sheerka/CLAUDE.md

Sheerka

Personal AI engine with a custom parsing and evaluation pipeline.

Project structure

src/
  core/          # Engine: Sheerka (orchestrator), ExecutionContext, Concept, ReturnValue, Event
  parsers/       # BNF/PEG parsers, tokenizer, state machine
  evaluators/    # Evaluation pipeline steps (DefConceptEvaluator, PythonEvaluator, etc.)
  services/      # Plugin services, loaded dynamically by introspecting BaseService subclasses
  ontologies/    # SheerkaOntologyManager — manages ontology state
  sdp/           # State/data persistence layer
  server/        # FastAPI server (main.py, authentication.py)
  caching/       # Cache, IncCache
  client.py      # CLI client
tests/           # Mirrors src/ structure; conftest.py provides shared fixtures

Common commands

# Run tests
pytest

# Run with coverage
make coverage        # runs coverage run + coverage html

# Start server
cd src && uvicorn server:app --reload

# Start client
python src/client.py --username <username> --password <password>

# Clean build artifacts
make clean

Architecture

Execution pipeline (in order): BEFORE_PARSING → PARSING → AFTER_PARSING → BEFORE_EVALUATION → EVALUATION → AFTER_EVALUATION

Services are discovered and loaded automatically via get_sub_classes("services", "services.BaseService.BaseService"). To add a service, subclass BaseService and implement initialize() and/or initialize_deferred().

Evaluators are similarly auto-loaded from subclasses of OneReturnValueEvaluator or AllReturnValuesEvaluator.

Collaboration rules

RULE-01 — Development Process

• Before writing any code, explain the available options and approaches.
• Validate the chosen approach together before producing code.
• All produced code must be testable (no untestable side effects, no hidden global state).

RULE-02 — Collaboration

• Ask questions to refine understanding or suggest alternative approaches.
• Ask questions one at a time. Wait for the answer to be fully understood before asking the next one.
• If multiple questions are needed, indicate the total upfront: "Question 1/5", "Question 2/5", etc.

RULE-03 — Communication

• Conversations may be in French or English depending on the language used.
• All code, documentation, and comments must be in English exclusively.

RULE-04 — Code Standards

• Python 3.12+. Follow PEP 8 conventions.
• Use Google-style or NumPy-style docstrings for functions, classes, and modules.
• snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE_CASE for constants.
• Type hints on all function signatures (parameters and return types).
• No emojis in code, comments, or docstrings.
• Use pathlib.Path for all file path manipulations in new code.
• Use the logging module (never print()).

RULE-05 — Dependency Management

• List all external dependencies required so they can be installed.
• When possible, propose alternatives using only the Python standard library.
• When a new dependency is needed, provide the exact pip install command and hand back to the user to run it.
• Never run pip install autonomously.
• Never modify requirements.txt directly — the user manages that file.

RULE-10 — Running Tests

• Do NOT run tests automatically. Always ask the user before running pytest.

RULE-11 — Functional Specifications as Source of Truth

• Feature specifications live in docs/ (named FEAT-NNN-<slug>.md).
• These specs are the authoritative source for expected behavior. In case of doubt between code and spec, the spec wins.
• Do NOT read specs systematically. Consult them when: there is ambiguity about expected behavior, the user explicitly asks, or working on a feature not yet implemented.
• When creating a new feature, propose a spec in docs/ before implementation.

Testing conventions

• Tests use pytest with pythonpath = "src tests" (set in pyproject.toml).
• conftest.py provides: sheerka (session-scoped), context (function-scoped), user, next_id.
• Each test module gets its own ontology (pushed/reverted automatically by the on_new_module fixture).
• tests/helpers.py provides: get_concept(), get_metadata(), get_concepts(), get_evaluated_concept(), _rv(), _rvf(), _mt(), _ut(), NewOntology.
• sheerka.initialize("mem://") is used in tests (in-memory, no disk I/O).
• Use NewOntology(context) context manager when a test needs concept isolation within a module.