Files

T

retoor 8df5cf7a45 Split monolithic tai.py into tai_pkg package, keep tai-orig.py as original

tai.py (8643 lines) is now a thin facade over tai_pkg/ (33 feature modules, one class or feature per file). tai-orig.py preserves the pre-split single-file version byte for byte (sha256 verified against snapshot); import tai and ./tai.py behavior unchanged.

Equivalence proof, all run on this tree immediately pre-commit: differential battery tai-orig.py vs facade 3718 checks 0 failures (surface, pure fuzz, tool dispatch, store/audit, release ops, fake-HOME install roundtrip, CLI runs); test_tai.py 261 OK; test_seal.py 16 OK; --version/--help byte-identical; dir(tai) zero removals.

Fix included: opencode wire-protocol schema echo leaked into replies; opencode_parse now scans with JSONDecoder.raw_decode capped at 200 scans (13 OpencodeParseTests). Test count 261 = 237 HEAD + 8 pre-existing uncommitted ToolArgumentsTests (now committed with this change, disclosed) + 13 OpencodeParseTests + 3 EmbeddedStringsTests. Patch-target-only test migration (24 hunks), zero assertion changes. tai_pkg clean-regenerated after mid-verification tamper was found and reverted.

2026-10-10 19:25:02 +02:00

4.6 KiB

Raw Blame History

AGENTS.md

Conventions

Use plain import and from statements in Python files.
Use the .py extension for Python source and test files.
Implementation lives in tai_pkg/, one feature per module, grouped into classes (instance classes for stateful clusters, static utility classes for stateless groups). tai.py is the thin facade: CLI entry plus the stable import tai surface re-exported from tai_pkg. Canonical patch targets are tai_pkg.<module>.<Class>.<name> (or the module attribute for module-level data); never patch through the tai. facade copies.
There are two kinds of test, in two different places, on purpose — see "Testing" below for the full split. In short: unit tests are top-level test_*.py; integration tests are tests/<topic>.py (no test_ prefix) built on tai_test.py.

Testing

Unit tests: test_tai.py, test_seal.py, at the repository top level, named test_*.py, unittest-based, import tai.py as a module directly, no subprocess, fast. python3 test_tai.py / python3 test_seal.py, or a single test via python3 -m unittest test_tai.SomeClass.test_method.

Integration tests: tests/<topic>.py (e.g. tests/rag.py), deliberately not named test_*.py and not at the top level, so the two kinds are never confused. These drive the real tai.py binary as a subprocess (one-shot or REPL) and check actual CLI behavior, using tai_test.py (the framework, at the repository root) as the one and only base to build on — never a one-off subprocess/asyncio harness per file. They must exercise a real LLM call through the real binary — never a mocked model or a database write standing in for what the agent would have done; the resulting flakiness from a free, rotating backend is accepted, not engineered away. Full conventions, that rule's full rationale, the required isolation rule (always a throwaway TAI_HOME), and why verification must check vault state rather than scrape CLI rendering, are in tests/README.md — read it before adding a new one. Run with python3 tests/<topic>.py (--filter, --interactive, --timeout all supported).

Agent Overview

tai: The main autonomous agent.
devops: A bot that manages the DevPlace DevOps platform.

Agent Profiles

default: Default agent profile for general tasks.
work: Work-focused agent profile.
dev: Development-focused agent profile.

Bot Details

devops: A bot that automates DevPlace DevOps operations.
- Manages workspaces, projects, and deployments.
- Handles user authentication and access control.
- Provides development tools and utilities.
- Integrates with OpenShift Dev Spaces.

Key Features

Autonomous decision making
Multi-profile support
Background subagent orchestration
Secure vault storage
Container sandbox support
Progress tracking
Interactive REPL
Command-line interface

Usage Examples

Start the main agent:
```
./tai.py
```
Use a specific profile:
```
./tai.py --profile work
```
Run a one-shot command:
```
./tai.py what is 2+3, use the shell
```
Check agent status:
```
./tai.py --version
```
Install the agent:
```
./tai.py --install
```

Development Guidelines

Write clear, concise code
Follow Python conventions
Test thoroughly
Use the agent for documentation
Keep code maintainable
Document decisions
Version control changes
Collaborate effectively

Research Rule

All external research conducted for this project (web searches, reading documentation to settle a design question, competitive/prior-art analysis) is archived under research/, maintained under the auspices of the Molodetz Institute — Research & Retrieval Division. The full specification — folder layout, the three required document types (Source Dossier, Source Citation Card, Conclusion Document), required metadata, and the quality bar — lives in research/README.md; research/INDEX.md is the living registry and statistics page. Read research/README.md in full before writing into this archive.

The binding rule, in short: a research task is not done until it is written into research/. Every source actually consulted gets its own document (Tier 1 if read and synthesized, Tier 2 if only seen in a result listing — never skipped, never inflated past what's actually known), every decision the research produced gets its own Conclusion document in that subject's conclusions/ folder, and research/INDEX.md gets updated in the same pass. Check research/INDEX.md for an existing subject before opening a new one.

4.6 KiB Raw Blame History