retoor
8df5cf7a45
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.
88 lines
4.6 KiB
Markdown
88 lines
4.6 KiB
Markdown
# 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
|
|
|
|
1. Start the main agent:
|
|
```bash
|
|
./tai.py
|
|
```
|
|
|
|
2. Use a specific profile:
|
|
```bash
|
|
./tai.py --profile work
|
|
```
|
|
|
|
3. Run a one-shot command:
|
|
```bash
|
|
./tai.py what is 2+3, use the shell
|
|
```
|
|
|
|
4. Check agent status:
|
|
```bash
|
|
./tai.py --version
|
|
```
|
|
|
|
5. Install the agent:
|
|
```bash
|
|
./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. |