Awam

Inspiration

When I build software, my first goal is to make it do what I want, and I rarely stop to think about what could go wrong. I add safety nets like strict types, but once the happy path works, most of my testing is just walking that same path. That doesn't prepare me for what happens when real people get their hands on the software. So I wondered: what if something could point out what I was missing, the gaps in my logic, however small?

What it does

Awam is a terminal tool that analyzes your code and points out where it can break. It raises each hole as a question, like "What happens if Y goes wrong?", so you have to think about how to catch or patch it. Awam can then generate tests that address the issues it flagged and run them, depending on the tag you run it with. If a test fails, it suggests how to fix the problem in your code. Awam only ever edits your test files, nothing else. The tags you can run with:

• no tag: a safe audit and inquiry mode. returns the questions, no tests generated
• generate: this generate the tests addressing the issues flagged
• run: this returns inquiry response with flagged cases, while running the tests available in your test files. It doesn't generate tests. If the tests fail, it would raises suggestions on how to get it to pass.

How I built it

I built Awam in Python, using Click and Rich for the terminal interface and Google Gemini as the AI model. It uses Python's ast library for syntax checks and pytest to execute the generated tests.

Challenges I ran into

• Running it like a real CLI on Windows: I wanted Awam to feel like a proper installed tool, so I had to add the Python Scripts folder to my PATH to run awam directly instead of python -m awam.cli.
• Rate limits: I hit rate-limiting issues with the model, so I switched to a lower-cost one and added retry logic to handle failures.

Accomplishments that I'm proud of

• Awam flags real issues in the code without hallucinating problems.
• It recognizes and acknowledges the tests that already exist.
• My favorite part is the failure suggestions. Instead of just saying a test failed, it tells you what to change so it passes.

What I learned

This was my first CLI tool, and my first time using a spec-driven approach. I used to start building and iterate as I went, but writing the spec first cut down a lot of the back-and-forth I normally deal with.

What's next for Awam

• Support more languages beyond Python such as Node, Go etc.
• Let users configure which kinds of error it should look for, such as input validation or error handling.

Built With

• click
• gemini
• pytest
• python
• rich