Metadata-Version: 2.4
Name: ficsit
Version: 0.1.0
Summary: A lightweight coding agent harness with tool execution and validation loops.
Author-email: Yibo Hu <yibohu@smail.nju.edu.cn>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/CaelusHu/Ficsit
Project-URL: Repository, https://github.com/CaelusHu/Ficsit.git
Project-URL: Issues, https://github.com/CaelusHu/Ficsit/issues
Keywords: agent,coding-agent,llm,openai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Ficsit

A lightweight coding agent harness with tool execution and validation loops.
"Fix it, just sit there."

## Installation

For an isolated command-line installation, use `pipx`:

```bash
pipx install ficsit
```

Alternatively, install it in your active Python environment:

```bash
pip install ficsit
```

## Quick Start

```bash
# Start Ficsit inside the project it may access
cd /path/to/your/project
ficsit

# Or start with a specific model
ficsit --model gpt-4o-mini

# Show the installed version without loading configuration
ficsit --version
```

The directory where `ficsit` starts is the active workspace. File reads, searches,
writes, and deletes are restricted to that directory; generated files are written
there directly and are not placed in an implicit `CODE/` directory.

## Configuration

API Key is stored in `~/.ficsit/.env` (automatically .gitignored).

```bash
ficsit config set key     # Enter API Key (hidden input)
ficsit config show key    # Show if set
ficsit config set base_url https://你的中转站/v1
ficsit config show
ficsit config delete base_url|model|key
```

## Built-in Commands

| Command | Description |
|---------|-------------|
| `/help` | Show help |
| `/status` | Show session status |
| `/memory` | View past session summaries |
| `/exit` | Exit and save session |

## Security

- API Key is stored in `~/.ficsit/.env` — a plaintext file. Ensure your home directory has appropriate permissions.
- `.env` is automatically added to `.gitignore` to prevent accidental commits.
- Guardian rules block dangerous operations (e.g., `rm -rf /`, system file writes).
- File tools cannot resolve paths outside the directory where Ficsit was started.
- Shell commands run with the workspace as `cwd`, but they are not an OS-level
  sandbox. Use a container or system sandbox before running untrusted code.
- Never hardcode credentials in code.

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
ruff check .
```

## Building A Release

```bash
python3 -m build
python3 -m twine check dist/*
```

This creates a wheel and source distribution in `dist/`. Release preparation,
clean-environment installation checks, and Trusted Publishing setup are documented
in [`docs/RELEASING.md`](docs/RELEASING.md).

## Project Structure

```
ficsit/
├── cli.py            # CLI entry point
├── config.py         # Configuration (TOML)
├── controller.py     # State machine controller
├── guardian.py       # Danger action guardrails
├── classifier.py     # Failure classification
├── memory.py         # Session memory
├── models.py         # Data models
├── repl.py           # REPL interface
├── llm/              # LLM client abstraction
├── states/           # State machine states
├── tools/            # Tool system
└── validators/       # Validation system
tests/
└── ...
```

## Platform Support

Python 3.11+, macOS / Windows / Linux.

## License

Ficsit is licensed under the [Apache License 2.0](LICENSE).

## Known Limitations

- Requires OpenAI API Key
- No streaming support
- Pure synchronous execution
